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

package/dist/types/security/ACLUtils.d.ts

@@ -1,35 +1,39 @@
-import { JWTUser } from "@rapidrest/core";
-import type { HttpRequest as Request } from "../http/index.js";
-import { AccessControlList, ACLAction, ACLRecord } from "./AccessControlList.js";
+import { type JWTUser } from "@rapidrest/core";
+import type { HttpRequest } from "../http/index.js";
+import { type AccessControlList, type ACLRecord } from "./AccessControlList.js";
 /**
  * Common utility functions for working with `AccessControlList` objects and validating user permissions.
+ *
+ * @author Jean-Philippe Steinmetz
  */
 export declare class ACLUtils {
+    private _objectFactory?;
     enabled: boolean;
-    private cacheTTL;
+    private cache?;
     private connMgr?;
     private logger?;
     private trustedRoles;
-    private get cacheClient();
     private get repo();
     private init;
     /**
-     * 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.
      */
-    private userMatchesId;
+    private matchSpecificity;
     /**
      * 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.
      */
-    checkRequestPerms(uid: string, user: JWTUser | undefined, req: Request): Promise<boolean>;
+    checkRequestPerms(uid: string, user: JWTUser | undefined, req: HttpRequest): Promise<boolean>;
     /**
      * Validates that the user has permission to perform the provided action using the given access control list.
      *
@@ -38,19 +42,43 @@ export declare class ACLUtils {
      * @param action The action that the user desires permission for.
      * @returns `true` if the user has at least one of the permissions granted for the given entity, otherwise `false`.
      */
-    hasPermission(user: JWTUser | undefined, acl: AccessControlList | string, action: ACLAction): Promise<boolean>;
+    hasPermission(user: JWTUser | undefined, acl: AccessControlList | string, action: string): Promise<boolean>;
     /**
      * 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.
      */
-    findACL(entityId: string, parentUids?: string[], reqCache?: Map<string, AccessControlList | null>): Promise<AccessControlList | null>;
+    findACL(entityId: string, parentUids?: string[], options?: {
+        skipCache?: boolean;
+    }): Promise<AccessControlList | undefined>;
     /**
-     * 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.
      */
-    removeACL(uid: string): Promise<void>;
+    removeACL(uid: string): Promise<AccessControlList | undefined>;
     /**
      * Compares two ACLs to see if they have been modified and returns the total number of changes between them.
      *
@@ -60,12 +88,31 @@ export declare class ACLUtils {
      */
     private diffACL;
     /**
-     * Stores the given access control list into the ACL database.
+     * Compares two lists of granted actions, ignoring order, to see if they differ.
+     */
+    private actionsChanged;
+    /**
+     * 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.
      */
-    saveACL(acl: AccessControlList): Promise<AccessControlList | null>;
+    saveACL(acl: AccessControlList, options?: {
+        preserveVersion?: boolean;
+    }): Promise<AccessControlList | null>;
     /**
      * Stores the given default access control list into the ACL database. A default ACL is a special type of ACL
      * that is primarily defined and maintained within the code but allows for user-specific overrides. To accomplish
@@ -80,7 +127,36 @@ export declare class ACLUtils {
      */
     saveDefaultACL(acl: AccessControlList): Promise<AccessControlList | null>;
     /**
-     * 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.
+     */
+    removeACLs(uids: string[]): Promise<AccessControlList[]>;
+    /**
+     * 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.
+     */
+    saveACLs(acls: AccessControlList[]): Promise<void>;
+    /**
+     * 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.

package/dist/types/security/AccessControlList.d.ts

@@ -1,27 +1,39 @@
 /**
- * Describes the various permission actions that can be performed against an entity.
+ * A set of conventional action strings recognized by the built-in CRUD routes and `RepoUtils`. `ACLRecord.actions`
+ * is not limited to these values — any arbitrary string may be granted (e.g. `"publish"`, `"document:archive"`) to
+ * express permissions beyond basic CRUD.
  *
  * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
  */
-export declare enum ACLAction {
-    CREATE = "CREATE",
-    DELETE = "DELETE",
-    FULL = "FULL",
-    READ = "READ",
-    SPECIAL = "SPECIAL",
-    UPDATE = "UPDATE"
-}
+export declare const ACLAction: {
+    /**
+     * Grants every action, including any action string not otherwise listed on the record. Supersedes all others.
+     */
+    readonly FULL: "*";
+    readonly COUNT: "count";
+    readonly CREATE: "create";
+    readonly DELETE: "delete";
+    readonly EXISTS: "exists";
+    readonly LIST: "list";
+    readonly READ: "read";
+    readonly TRUNCATE: "truncate";
+    readonly UPDATE: "update";
+};
 /**
- * The `ACLRecord` interface describes a single permissions entry in an `AccessControlList` that grants or denies
- * a set of permissions to a single user or role.
+ * The `ACLRecord` interface describes a single permissions entry in an `AccessControlList` that grants a set of
+ * actions to a single user or role.
  *
- * Each permission can be one of the following actions:
- * - `Create` - The user or role can create a new record or object.
- * - `Read` - The user or role can read the record or object.
- * - `Update` - The user or role can modify existing records or objects.
- * - `Delete` - The user or role can delete existing records or objects.
- * - `Special` - The user or role has special prilieges to edit the ACL permissions.
- * - `Full` - The user or role has total control over the record or object and supersedes any of the above.
+ * `actions` is an arbitrary list of action strings the user or role is granted for the entity. The conventional
+ * CRUD actions are defined in `ACLAction`, but any string may be used to express custom, service-specific
+ * permissions. The sentinel value `ACLAction.FULL` (`"*"`) grants every action and supersedes all others.
+ *
+ * If no record matches a given user or role, permission is looked up on the `parent` ACL (see `parentUid`)
+ * instead. There is no per-action inheritance within a single matched record — if a record matches, only the
+ * actions it explicitly lists are granted.
+ *
+ * ACLs can be chained via single inheritance through the specification of the `parentUid`. This allows the ability to
+ * create complex trees of permissions that can easily inherit control schemes to make the definition of permissions
+ * easier.
  *
  * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
  */
@@ -31,52 +43,18 @@ export interface ACLRecord {
      */
     userOrRoleId: string;
     /**
-     * Indicates that the user or role has permission to create new records of the entity.
+     * The list of actions this user or role is granted for the entity. `ACLAction.FULL` (`"*"`) grants everything.
      */
-    create: boolean | null;
-    /**
-     * Indicates that the user or role has permission to read records of the entity.
-     */
-    read: boolean | null;
-    /**
-     * Indicates that the user or role has permission to modify existing records of the entity.
-     */
-    update: boolean | null;
-    /**
-     * Indicates that the user or role has permission to delete existing records of the entity.
-     */
-    delete: boolean | null;
-    /**
-     * Indicates that the user or role has special permission over records of the entity. The exact meaning of this
-     * may vary by service.
-     */
-    special: boolean | null;
-    /**
-     * Indicates that the user or role has total control over records of the entity. This supersedes all of the above
-     * permissions.
-     */
-    full: boolean | null;
+    actions: string[];
 }
 /**
  * The access control list provides a generic interface for the storage of user and roles permissions. Each ACL object
  * represents the permission set for a single entity within the system. The entity is identified generically by its
- * universally unique identifier (`uuid`). Each entry in the ACL records the permissions available to a particular user
- * or role.
- *
- * Each permission can be one of the following actions:
- * - `Create` - The user or role can create a new record or object.
- * - `Read` - The user or role can read the record or object.
- * - `Update` - The user or role can modify existing records or objects.
- * - `Delete` - The user or role can delete existing records or objects.
- * - `Special` - The user or role has special prilieges to edit the ACL permissions.
- * - `Full` - The user or role has total control over the record or object and supersedes any of the above.
+ * universally unique identifier (`uuid`). Each entry in the ACL records the set of actions granted to a particular
+ * user or role (see `ACLRecord`).
  *
- * For each of the above actions the user or role will be granted either an `allow` permission or a `deny` permission.
- * If an `allow` is granted, the user or role has permission to perform that action. If a `deny` is set, then the user
- * or role is denied that action. If no explicit `allow` or `deny` is set then the user or role will inherit the
- * permission from a parent role or ACL.
- *
- * ACLs can be chained via single inheritance through the specification of the `parentUid`. This allows the ability to
+ * If no record in this ACL matches a given user or role, permission is looked up on the `parent` ACL instead. ACLs
+ * can be chained via single inheritance through the specification of the `parentUid`. This allows the ability to
  * create complex trees of permissions that can easily inherit control schemes to make the definition of permissions
  * easier.
  *
@@ -90,7 +68,7 @@ export interface AccessControlList {
     /**
      * The parent access control list that this instance inherits permissions from.
      */
-    parent?: AccessControlList | null;
+    parent?: AccessControlList;
     /**
      * The universally unique identifier of the parent `AccessControlList` that this object will inherit permissions
      * from.

package/dist/types/security/AccessControlListMongo.d.ts

@@ -1,16 +1,11 @@
 import { BaseMongoEntity } from "../models/index.js";
-import { AccessControlList, ACLRecord } from "./AccessControlList.js";
+import type { AccessControlList, ACLRecord } from "./AccessControlList.js";
 /**
  * Implementation of the `ACLRecord` interface for use with MongoDB databases.
  */
 export declare class ACLRecordMongo implements ACLRecord {
     userOrRoleId: string;
-    create: boolean | null;
-    read: boolean | null;
-    update: boolean | null;
-    delete: boolean | null;
-    special: boolean | null;
-    full: boolean | null;
+    actions: string[];
     constructor(other?: any);
 }
 /**
@@ -18,7 +13,7 @@ export declare class ACLRecordMongo implements ACLRecord {
  */
 export declare class AccessControlListMongo extends BaseMongoEntity implements AccessControlList {
     parent?: AccessControlList;
-    parentUid?: string | undefined;
+    parentUid?: string;
     records: ACLRecordMongo[];
     constructor(other?: any);
 }

package/dist/types/security/AccessControlListSQL.d.ts

@@ -1,16 +1,11 @@
 import { BaseEntity } from "../models/BaseEntity.js";
-import { AccessControlList, ACLRecord } from "./AccessControlList.js";
+import type { AccessControlList, ACLRecord } from "./AccessControlList.js";
 /**
  * Implementation of the `ACLRecord` interface for use with SQL databases.
  */
 export declare class ACLRecordSQL implements ACLRecord {
     userOrRoleId: string;
-    create: boolean | null;
-    read: boolean | null;
-    update: boolean | null;
-    delete: boolean | null;
-    special: boolean | null;
-    full: boolean | null;
+    actions: string[];
     constructor(other?: any);
 }
 /**
@@ -18,7 +13,7 @@ export declare class ACLRecordSQL implements ACLRecord {
  */
 export declare class AccessControlListSQL extends BaseEntity implements AccessControlList {
     parent?: AccessControlList;
-    parentUid?: string | undefined;
+    parentUid?: string;
     records: ACLRecordSQL[];
     constructor(other?: any);
 }

package/dist/types/security/BaseACLRoute.d.ts

@@ -0,0 +1,73 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { type AccessControlList } from "./AccessControlList.js";
+import { type JWTUser } from "@rapidrest/core";
+import type { UpdateObject } from "../routes/ModelRoute.js";
+import { CRUDRoute } from "../routes/CRUDRoute.js";
+/**
+ * The `BaseACLRoute` class provides a base set of endpoints for managing Access Control List records.
+ *
+ * Exposed endpoints:
+ *
+ * | Name | HTTP Method | What it does |
+ * | --- | --- | --- |
+ * | `count` | `HEAD /` | Counts the number of ACLs matching the provided set of criteria in the request's query parameters. Returns the count as the value of the `Content-Length` header. |
+ * | `create` | `POST /` | Adds one or more new ACLs to the datasource. |
+ * | `delete` | `DELETE /:id` | Removes an existing ACL from the datasource. |
+ * | `exists` | `HEAD /:id` | Checks if the ACL with the given ID exists in the datasource. Sets `Content-Length` header to `1` if the ACL exists, otherwise `0`. |
+ * | `find` | `GET /` | Returns all ACLs matching the provided set of criteria in the request's query parameters. |
+ * | `findById` | `GET /:id` | Returns a single ACL with a specified unique identifier. |
+ * | `truncate` | `DELETE /` | Removes all ACLs from the datasource. |
+ * | `update` | `PUT /:id` | Modifies an existing ACL in the datasource. |
+ * | `updateBulk` | `PUT /` | Modifies multiple existing ACLs in the datasource. |
+ * | `updateProperty` | `PUT /:id/:property` | Modifies an single property of the given name of an existing ACL in the datasource. |
+ *
+ * !!Note!! that the `BaseACLRoute` is not automatically registered with a server by default. You must create
+ * your own class that extends `BaseACLRoute` and apply the desired base path with `@Route()`.
+ *
+ * @example
+ * ```ts
+ * import { AccessControlListMongo, BaseACLRoute, RouteDecorators } from "@rapidrest/service-core";
+ * const { Model, Route } = RouteDecorators;
+ *
+ * @Model(AccessControlListMongo)
+ * @Route("/acls")
+ * export class ACLRoute extends BaseACLRoute<AccessControlListMongo> {}
+ * ```
+ * @example
+ * ```ts
+ * import { AccessControlListSQL, BaseACLRoute, RouteDecorators } from "@rapidrest/service-core";
+ * const { Model, Route } = RouteDecorators;
+ *
+ * @Model(AccessControlListSQL)
+ * @Route("/acls")
+ * export class ACLRoute extends BaseACLRoute<AccessControlListSQL> {}
+ * ```
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class BaseACLRoute<T extends AccessControlList> extends CRUDRoute<T> {
+    protected checkPerms(params: any, user: JWTUser): Promise<void>;
+    /**
+     * The `default_<uid>` records are regenerated from code on every server startup (see
+     * `ACLUtils.saveDefaultACL`) and exist solely to seed the user-editable override record. They must never be
+     * deleted or modified directly, even by an administrator, since doing so would have no lasting effect and would
+     * only cause confusion.
+     */
+    protected checkNotDefault(id: string): void;
+    /**
+     * Bulk updates have no `:id` URI parameter to check a per-record permission against, so unlike `checkPerms`
+     * we can't fall back to a per-record `FULL` permission check here. Require a trusted role for every bulk
+     * update instead, and disallow touching any `default_<uid>` record (see `checkNotDefault`).
+     */
+    protected checkPermsBulk(objs: UpdateObject<T>[], user: JWTUser): void;
+    count(params: any, query: any, res: HttpResponse, user?: JWTUser): Promise<any>;
+    create(obj: T | T[], req: HttpRequest, user?: JWTUser): Promise<T | Array<T>>;
+    delete(id: string, version: string | undefined, purge: string | undefined, req: HttpRequest, user?: JWTUser): Promise<void>;
+    exists(id: string, query: any, res: HttpResponse, user?: JWTUser): Promise<any>;
+    find(params: any, query: any, user?: JWTUser): Promise<Array<T>>;
+    findById(id: string, query: any, user?: JWTUser): Promise<T | null>;
+    truncate(params: any, query: any, user?: JWTUser): Promise<void>;
+    update(id: string, obj: UpdateObject<T>, req: HttpRequest, user?: JWTUser): Promise<T>;
+    updateProperty(id: string, propertyName: string, obj: any, user?: JWTUser): Promise<T>;
+    updateBulk(obj: UpdateObject<T>[], req: HttpRequest, user?: JWTUser): Promise<T[]>;
+}

package/dist/types/security/index.d.ts

@@ -1,2 +1,5 @@
 export * from "./AccessControlList.js";
+export * from "./AccessControlListMongo.js";
+export * from "./AccessControlListSQL.js";
 export * from "./ACLUtils.js";
+export * from "./BaseACLRoute.js";

package/dist/types/test/request.d.ts

@@ -8,10 +8,12 @@ export interface TestResponse {
     type: string;
     headers: Record<string, string>;
     ok: boolean;
+    /** True for 3xx responses that carry a Location header, matching superagent's `res.redirect`. */
+    redirect: boolean;
 }
 /**
  * Creates a supertest-style request builder that sends requests via axios to
- * `http://localhost:<port>`.
+ * `http://localhost:<port>`. No cookie persistence between calls — each call is independent.
  */
 export declare function request(app: any): {
     get: (url: string) => any;
@@ -22,3 +24,18 @@ export declare function request(app: any): {
     head: (url: string) => any;
     options: (url: string) => any;
 };
+/**
+ * Creates a supertest `.agent()`-style request builder that persists cookies across every call
+ * made through it, matching real browser behavior. Use this for multi-request flows where a
+ * server-set cookie (e.g. a session cookie) must be sent back on a later request — a plain
+ * `request(app)` call issues a stateless request each time and never resends cookies.
+ */
+export declare function agent(app: any): {
+    get: (url: string) => any;
+    post: (url: string) => any;
+    put: (url: string) => any;
+    delete: (url: string) => any;
+    patch: (url: string) => any;
+    head: (url: string) => any;
+    options: (url: string) => any;
+};