@rapidrest/service-core 2.0.0 → 2.1.1

package/dist/types/models/RepoUtils.d.ts

@@ -36,6 +36,25 @@ export interface RepoOperationOptions {
 export interface RepoCreateOptions extends RepoOperationOptions {
     /** The AccessControlList to use when creating a new object. */
     acl?: AccessControlList;
+    /**
+     * Set to `true` to let a record-level-ACL create adopt an ACL that already exists at the new record's uid even
+     * though no record of this model exists there yet and the caller doesn't already hold every creator right on
+     * it. The existing ACL is used as-is (the creator is not added to it). Defaults to `false`, in which case such
+     * a create is refused with `IDENTIFIER_EXISTS` - see `create()`.
+     *
+     * For trusted server-side code only (e.g. code that deliberately saves a record's ACL before the record
+     * itself) - this must never be derived from a client request.
+     */
+    allowExistingACL?: boolean;
+    /**
+     * Set to `true` to keep the `_id` carried by the object being created instead of discarding it. The object is
+     * still always inserted, never merged into an existing document: a create whose `_id` is already taken fails
+     * with `IDENTIFIER_EXISTS`. Defaults to `false`.
+     *
+     * For trusted server-side code only (e.g. restoring or migrating documents with their original `_id`) - this
+     * must never be derived from a client request.
+     */
+    preserveId?: boolean;
 }
 /**
  * The available options for the `RepoUtils.delete()` operation.
@@ -73,6 +92,18 @@ export interface RepoFindOptions extends RepoOperationOptions {
 export interface RepoUpdateOptions<T extends BaseEntity | SimpleEntity> extends RepoOperationOptions {
     /** The desired version number of the resource to update. */
     version?: number | string;
+    /**
+     * Set to `true` to let this update actually write `@ReadOnly` fields instead of unconditionally
+     * resetting them back to their existing persisted value. Defaults to `false` (the field is protected),
+     * matching this method's behavior prior to this option's introduction.
+     *
+     * For trusted server-side code only - this must never be derived from a client request. It exists for
+     * a caller that legitimately owns a `@ReadOnly` field's lifecycle outside the ordinary create/update
+     * path (e.g. a background job or route handler computing and persisting a system-managed value), where
+     * the alternative would be bypassing `RepoUtils.update()` entirely (losing its ACL/optimistic-locking/
+     * transaction handling) just to change that one field.
+     */
+    allowReadOnly?: boolean;
 }
 /**
  * @author Jean-Philippe Steinmetz
@@ -95,18 +126,46 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
     constructor(modelClass: any, repo?: Repository<T> | MongoRepository<T>);
     protected init(): Promise<void>;
     /**
-     * Retrieves every uid matching the given (already-built) search query, ignoring any pagination `take`/`page`
-     * baked into it by `ModelUtils.buildSearchQuery`. Used by `count`/`exists`/`truncate`, which must narrow by
-     * record-level ACLs against the *entire* matching set rather than a single page of it — applying the default
-     * `take` here would silently undercount, under-check existence for, or under-delete a large result set.
+     * Retrieves the uids matching the given (already-built) search query, ignoring any pagination `take`/`page`
+     * baked into it by `ModelUtils.buildSearchQuery`, unless `cap` is given.
+     *
+     * Without `cap` the whole matching set is returned. Pass `cap` whenever each uid will cost a per-record ACL check
+     * on behalf of a client that acts on the records (`truncate()` on a `recordACL` model): otherwise a single anonymous
+     * request can trigger unbounded ACL work, and on MongoDB a `distinct` over enough uids exceeds the 16MB reply limit.
+     * `count()` must report the true total, so it never uses this - see `countPermittedUids()`.
+     *
+     * @param cap The maximum number of uids to return.
      */
     private findAllUids;
+    /**
+     * Returns the maximum number of records a client request may have checked individually against record-level
+     * ACLs: the `take` that `ModelUtils.buildSearchQuerySQL()` already resolved onto the built SQL query. A MongoDB
+     * query carries no `take`, so the same rule is read from `ModelUtils.resolvePagination()`, the helper that
+     * documents it for MongoDB callers.
+     */
+    private recordACLCap;
+    /**
+     * Determines whether a built search query can match soft-deleted records: every OR branch must pin `deleted` to
+     * exactly `false` for it not to. Decided from the compiled query rather than the raw client value, so any
+     * spelling of the filter (`true`, `eq(true)`, `in(true,false)`, `ne(false)`, a repeated parameter, a `$or`
+     * branch) is recognized. Always `false` for a model that isn't recoverable.
+     */
+    private queryIncludesDeleted;
     /**
      * Filters the given uids down to those the user has `action` permission for, checking in bounded-size
      * batches rather than a single unbounded `Promise.all` so a large matching set can't fire an unbounded
      * number of concurrent permission-check round trips at once.
      */
     private filterPermittedUids;
+    /**
+     * Counts the records matched by an (already-built) search query that the caller holds the given permission(s) on,
+     * for a `recordACL` model. Unlike `findAllUids()` this is never capped - a count must be the true total - but it
+     * never holds the whole matching set either: MongoDB streams uids from a projected cursor instead of a `distinct`
+     * (whose single reply is limited to 16MB), and permissions are checked in bounded batches as the uids arrive.
+     *
+     * @param actions Every action the caller must hold on a record for it to be counted.
+     */
+    private countPermittedUids;
     count(query: any, options?: RepoFindOptions): Promise<number>;
     /**
      * Determines whether an object with the given unique identifier (and, optionally, a specific version) exists
@@ -153,6 +212,85 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
      * @param options The additional options to consider during the search.
      */
     findOne(id: string, options?: RepoFindOptions): Promise<T | undefined>;
+    /**
+     * Resolves the per-record ACL for a record about to be created by `create()` under `uid`. Returns `uid` when a
+     * fresh ACL was created for it (so the caller can clean it up if the create fails), or `undefined` when an
+     * existing ACL is legitimately reused as-is.
+     *
+     * ACLs live in one global collection keyed only by uid, shared by every model and by the class/route ACLs, and a
+     * create's uid can come from the client. An ACL that already exists at `uid` may guard a record of another model,
+     * a whole model or route, or have been planted there by another user ahead of time - adopting it would hand
+     * whoever holds rights on it the new record, or hand the creator whatever it protects. So:
+     * - a code-defined ACL uid (a class, route or endpoint ACL, or any `default_*` uid; see
+     * `ACLUtils.isReservedUid()`/`isProtectedACL()`) is never claimed or reused, whoever the caller is;
+     * - an existing ACL is reused, unchanged, only for a trackChanges "new version" of an existing record
+     * (`count > 0`; `create()` has already verified the caller's UPDATE right on that record), or when trusted
+     * server code passed `allowExistingACL`. Neither a trusted role nor already holding rights on it is enough.
+     *
+     * Otherwise the create is refused with `IDENTIFIER_EXISTS`, the same error as a record identifier collision.
+     * A genuinely orphaned ACL can't be reliably told apart from one guarding another model's record, so no attempt
+     * is made to replace it. A fresh ACL is claimed with `saveACL()`'s `createOnly` mode, so two concurrent creates
+     * (of the same or of different models) can't both claim the same uid either.
+     */
+    private claimRecordACL;
+    /**
+     * Converts every `Date`-typed property of `obj` that holds a string or number (e.g. an ISO 8601 string from a
+     * JSON request body) to a real `Date`, in place. Without this a MongoDB document stores the string itself, and
+     * date range queries (which compare against `Date` operands) never match it.
+     *
+     * A property counts as `Date`-typed when its `@Column` declares an explicit date/time `type`, or otherwise when
+     * TypeScript's emitted `design:type` is `Date`. TypeScript reflects a union-typed property (e.g. `Date | null`)
+     * as `Object`, so such a property is only converted when its `@Column` sets `type` explicitly. Properties that
+     * aren't `@Column`s are never touched.
+     *
+     * Accepted values (anything else, including a `Date` column holding a boolean or an object, is a 400):
+     * - an ISO 8601 date (`YYYY-MM-DD`) or date-time (`YYYY-MM-DDTHH:mm[:ss[.fff]]`, `T` or a space), with a zone
+     * designator of `Z`, `±HH`, `±HHmm` or `±HH:mm`. A date-time without a zone is read as UTC, never as the server's
+     * local time;
+     * - a finite number of epoch milliseconds between years 1 and 9999 whose magnitude is at least `1e11` (a smaller
+     * number is ambiguous with epoch seconds). Numeric strings are not accepted;
+     * - a `Date`, `null` or `undefined`, which are left as they are.
+     *
+     * A SQL date-only column (`@Column({ type: "date" })`) is validated as a `YYYY-MM-DD` string but kept as that
+     * string: TypeORM writes a `Date` into such a column using the server's local calendar date, so converting it
+     * would store the previous day on any server west of UTC. On MongoDB, which has no date-only type, it is
+     * converted to midnight UTC like any other date.
+     *
+     * @param obj The object whose properties to convert.
+     * @param clazz The model class describing `obj`.
+     * @throws ApiError `INVALID_REQUEST` (400) when a value isn't a valid date.
+     */
+    protected coerceDateProperties(obj: any, clazz: any): void;
+    /**
+     * Returns the date-typed `@Column`s of `clazz` (see `coerceDateProperties()`), computed once per class.
+     */
+    private static getDateColumns;
+    /**
+     * Parses a client-supplied date value: an ISO 8601 string or a number of epoch milliseconds (see
+     * `coerceDateProperties()` for the exact rules). Returns `undefined` for anything else.
+     */
+    private static parseDateInput;
+    /**
+     * Strictly parses an ISO 8601 date (`YYYY-MM-DD`) or, unless `dateOnly`, date-time string, rejecting impossible
+     * calendar values (e.g. `2026-02-30`) that `new Date()` would silently roll over. A date-time without a zone is
+     * read as UTC.
+     */
+    private static parseISODate;
+    /**
+     * Rejects update input with a top-level key that MongoDB would interpret as something other than a plain field
+     * name: a dotted path (`"aliases.3"`, which writes a nested element) or an operator (`"$inc"`). Such a key
+     * bypasses route/model validation (which only knows the model's real property names), so it is refused on
+     * every backend rather than passed through.
+     *
+     * @throws ApiError `INVALID_REQUEST` (400) naming the first offending key.
+     */
+    private assertPlainPropertyNames;
+    /**
+     * Determines whether `existing` is under optimistic locking: a `BaseEntity` instance or - for a `BaseEntity`
+     * model - any object carrying a numeric `version`, such as a plain document read straight from a
+     * `MongoRepository` (whose `find()`/`findOne()` return plain documents, not model instances).
+     */
+    private isVersioned;
     /**
      * Returns the default access control list governing the model type. Returning a value of `undefined` will grant
      * full acccess to any user (including unauthenticated anonymous users).
@@ -208,6 +346,104 @@ export declare class RepoUtils<T extends BaseEntity | SimpleEntity> {
     searchIdQuery(id: string, version?: number | string, includeDeleted?: boolean): any;
     truncate(query: any, options: RepoFindOptions): Promise<void>;
     update(obj: Partial<T>, existing: T, options?: RepoUpdateOptions<T>): Promise<T>;
+    /**
+     * Maps an error thrown by one of `update()`'s writes: a duplicate key on the record's identity (`_id`/primary key
+     * or `(uid, version)`) is a lost optimistic-lock race (409 `INVALID_OBJECT_VERSION`), and a duplicate value of any
+     * other unique column is a 400 `IDENTIFIER_EXISTS`. Any other error is returned as is.
+     *
+     * @param err The error thrown by the write.
+     * @param versionInsert Whether the write inserted a new version (`trackChanges`), which makes an unidentified
+     * duplicate key most likely a version clash.
+     */
+    private mapUpdateWriteError;
+    /**
+     * Counts the stored rows/documents (every version, deleted or not) whose identifier matches `id`, ignoring ACLs.
+     *
+     * @param id The identifier, or identifiers, to match.
+     * @param txInfo The active transaction, if any.
+     * @param clazz The model class to build the identifier query for.
+     */
+    private countById;
+    /**
+     * Reads the stored version of `existing` straight from the database, without ACL checks, caching or scoped
+     * property removal. Used by `update()` when `existing` lacks fields it must carry over.
+     */
+    private loadStoredRecord;
+    /** Matches a whole-word `me` anywhere in a serialized query (see `find()`'s cache key). */
+    private static readonly REGEX_ME;
+    /**
+     * Returns whether this model keeps every version of a record as its own immutable row/document (`trackChanges`),
+     * which is what makes a version-specific cache entry safe to keep until it expires.
+     */
+    private get versionsAreImmutable();
+    /** Parses a `version` option the way `searchIdQuery()` does. */
+    private parseVersion;
+    /**
+     * Returns the cache key of a single record: its latest version, or (only for a model whose versions are immutable)
+     * a specific version. Returns `undefined` for a specific version of any other model, which is never cached: its
+     * entry would outlive the in-place update that replaces that version.
+     *
+     * Record keys (`rec:`) and query result keys (`q:`) are distinct namespaces, so no client-chosen uid can ever name
+     * a query result entry (or the other way around).
+     */
+    private recordCacheKey;
+    /** Returns the cache key of a `find()` result for the given (JSON-serializable) key material. */
+    private queryCacheKey;
+    /**
+     * Determines whether a cached record really is the one identified by `id` (and `version`, when given): one of the
+     * model's identifier properties must hold `id`. Guards against a cache entry written under a colliding key.
+     */
+    private matchesId;
+    /**
+     * Returns a shallow copy of `record` with the same prototype, for handing out (or stripping) without altering the
+     * object a cache holds.
+     */
+    private copyRecord;
+    /**
+     * Stores a copy of `record` in the cache under its latest-version key, and under its version key when versions are
+     * immutable. Fire-and-forget: a cache failure never fails the write.
+     */
+    private cacheRecord;
+    /**
+     * Caches a page of `find()` results: each record under its own record key, and the query key as the list of those
+     * records' `[uid, version]` references. A record of a model whose versions are immutable is referenced by its
+     * version (a list may hold past versions); any other record by its latest-version key, which `update()` refreshes
+     * and `delete()` removes, so a cached list never serves a stale or deleted record.
+     */
+    private cacheResults;
+    /**
+     * Loads a cached page of `find()` results (see `cacheResults()`). Records that have since expired, been deleted, or
+     * whose entry isn't the referenced record are left out; an empty array means nothing usable was cached.
+     */
+    private loadCachedResults;
+    /**
+     * Returns the version-specific cache keys of every stored version of the given records (only for a model whose
+     * versions are cached individually; otherwise none). Must be called before the records are removed.
+     */
+    private versionCacheKeys;
+    /**
+     * Removes the cached entries of the given records: their latest-version keys plus `versionKeys` (see
+     * `versionCacheKeys()`). Fire-and-forget: a cache failure never fails the write.
+     */
+    private uncacheRecords;
+    /**
+     * Returns whether this is the ACL model itself (served by e.g. a `BaseACLRoute`), whose documents `ACLUtils`
+     * caches separately under their uids.
+     */
+    private get isACLModel();
+    /**
+     * After a write to the ACL model, drops `ACLUtils`' cached copies of the written ACLs so permission checks see the
+     * change right away (they would otherwise keep using the old ACL until its cache entry expired). A failure is
+     * logged rather than failing the write, which has already happened.
+     */
+    private invalidateACLCache;
+    /**
+     * Sends a push notification about a write, unless `skipPush` is set. The payload is a copy with every
+     * `@RequiresScope` property removed: subscribers only need READ on the record's channel, and the writer's scopes
+     * say nothing about theirs, so no scoped value is ever published. Consumers that need a scoped value must fetch
+     * the record, which applies their own scopes.
+     */
+    private publish;
     /**
      * Performs validation on the object(s) provided. This function first calls `ObjectUtils.validate()` to check
      * any class level defined validation functions. Second, it scans for any properties with the `@Reference`

package/dist/types/routes/BasePushRoute.d.ts

@@ -48,6 +48,11 @@ export declare class BasePushRoute {
      * clobber (or exceed the cap on) each other's committed subscription list.
      */
     private runExclusive;
+    /**
+     * Returns `true` if the given socket is closing or closed. Works for the `ws` library's sockets as well as the
+     * uWS and Bun shims, which all use the WebSocket `readyState` values (2 = CLOSING, 3 = CLOSED).
+     */
+    private isSocketClosed;
     connect(sock: ws, user: any): Promise<void>;
     send(id: string, msg: any, user: any): Promise<void>;
 }

package/dist/types/routes/CRUDRoute.d.ts

@@ -38,6 +38,16 @@ export declare abstract class CRUDRoute<T extends BaseEntity | SimpleEntity> ext
      */
     protected validateCreate(obj: Partial<T>, user?: JWTUser): Promise<void>;
     private validateCreateBulk;
+    /**
+     * Returns `err` if it is an `ApiError`, otherwise a generic `INVALID_REQUEST` error. A validator's `ApiError` is
+     * meant for the client, but any other error (e.g. a driver error from a custom validator) may expose internals.
+     */
+    private static toValidationError;
+    /**
+     * Throws a `BulkError` when at least one object in a bulk request failed validation. The `BulkError` holds one
+     * entry per object, in request order: `null` for an object that passed, otherwise the reason it failed.
+     */
+    private static throwBulkValidationErrors;
     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>;

package/dist/types/routes/RouteUtils.d.ts

@@ -1,4 +1,4 @@
-import type { RequestHandler } from "../http/types.js";
+import type { HttpRequest, RequestHandler } from "../http/types.js";
 import { RateLimiter } from "../RateLimiter.js";
 import { RateLimitOptions } from "../decorators/RouteDecorators.js";
 /**
@@ -13,13 +13,37 @@ export declare class RouteUtils {
     private logger?;
     protected rateLimiter?: RateLimiter;
     protected trustedRoles: string[];
+    protected trustedProxies: string[];
     /**
      * Creates a middleware function that checks if the user has elevated privileges and if not
      * throws the `AUTH_REQUIRES_ELEVATION` error.
      */
     checkElevation(lastStart?: number): RequestHandler;
+    /**
+     * Returns a canonical form of a request path for use in rate limit identifiers. The router percent-decodes
+     * `:param` values, so `/clients/%61bc` and `/clients/abc` reach the same handler. Keying on the raw path would
+     * give an attacker a separate bucket for every encoding variant. Each segment is decoded and then re-encoded
+     * (a malformed segment is kept as is), and empty segments from repeated or trailing slashes are dropped.
+     *
+     * @param path The request path to normalize.
+     */
+    static normalizeRateLimitPath(path: string): string;
+    /**
+     * Returns the path part of a rate limit identifier for `req`. When the router has set `req.routePattern`, the
+     * pattern is used with each `:param` segment replaced by its decoded value from `req.params`, re-encoded. A
+     * pattern with a `*` wildcard can't be rebuilt from params, so it and a request without a pattern fall back to
+     * `normalizeRateLimitPath(req.path)`.
+     *
+     * @param req The request to build the identifier path for.
+     */
+    static getRateLimitPath(req: HttpRequest): string;
     /**
      * Creates a middleware function that performs rate limiting on the request.
+     *
+     * The identifier is `options.id` when set. Otherwise it is the request method plus the matched route pattern with
+     * its decoded params, or the normalized request path (see `getRateLimitPath()`). With `options.perUser`, an authenticated caller gets a bucket keyed on their
+     * uid and an anonymous caller gets a bucket keyed on their client IP address, so one anonymous client can't
+     * exhaust the limit for every other anonymous caller.
      */
     checkRateLimiter(options: RateLimitOptions): RequestHandler;
     /**
@@ -63,6 +87,18 @@ export declare class RouteUtils {
      * @returns The list of `@Method` decorated functions that were found.
      */
     getRouteMethods(route: any): Map<string, any>;
+    /**
+     * Persists a `@Protect` ACL declared on a route class or handler.
+     *
+     * Registration fails closed. If the ACL can't be saved (for example the `acl` datastore is unavailable at
+     * startup), the error is rethrown so the route is never registered. If it saves but `saveDefaultACL()`
+     * returns no user-editable ACL, an error is logged. The route is still registered with its permission check
+     * keyed on the declared uid, and `ACLUtils.checkRequestPerms()` denies every request until that ACL exists.
+     *
+     * @param aclUtils The ACL utilities to save with.
+     * @param acl The ACL declared by `@Protect`.
+     */
+    private saveRouteACL;
     /**
      * Registers the provided route object containing a set of decorated endpoints to the server.
      *

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

@@ -13,6 +13,11 @@ export declare class ACLUtils {
     private cache?;
     private connMgr?;
     private logger?;
+    /**
+     * The uids of every code-defined (class, route and endpoint) ACL registered via `saveDefaultACL()` in this
+     * process, together with their `default_<uid>` counterparts. See `isReservedUid()`.
+     */
+    private reservedUids;
     private trustedRoles;
     private get repo();
     private init;
@@ -25,6 +30,30 @@ export declare class ACLUtils {
      * match, or `"none"` if the user doesn't match this id at all.
      */
     private matchSpecificity;
+    /**
+     * Determines whether `uid` names a code-defined ACL: any `default_<uid>` ACL, or a class/route/endpoint ACL (or
+     * its `default_` counterpart) registered through `saveDefaultACL()`. Such an ACL governs a whole model or route,
+     * so a record must never be created at, adopt, or remove it (see `RepoUtils.create()`/`delete()`/`truncate()`).
+     *
+     * @param uid The ACL uid to check.
+     */
+    isReservedUid(uid: string | undefined): boolean;
+    /**
+     * Determines whether `acl` is a code-defined ACL: its uid is reserved (see `isReservedUid()`), or it has the
+     * shape of the user-editable half of a default ACL (its parent is `default_<uid>`). The latter also catches one
+     * registered by a route or model that this process doesn't load.
+     *
+     * @param acl The ACL to check.
+     */
+    isProtectedACL(acl: AccessControlList | undefined | null): boolean;
+    /**
+     * Drops the cached copies of the given ACLs, so the next permission check reads them from the database. Any code
+     * that writes ACL documents without going through `saveACL()`/`removeACL()` must call this (e.g. `RepoUtils`
+     * serving the ACL REST routes).
+     *
+     * @param uids The uids of the ACLs to invalidate.
+     */
+    invalidateACLs(uids: string[]): Promise<void>;
     /**
      * 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` datasource has not been configured
@@ -55,11 +84,13 @@ export declare class ACLUtils {
      * @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.
+     * mirrors `RepoUtils`'s `RepoFindOptions.skipCache` (applies to the whole parent chain). A database read is
+     * written back into the cache afterward. Set `skipParents: true` to not populate the parent chain at all, when
+     * only the ACL itself is needed.
      */
     findACL(entityId: string, parentUids?: string[], options?: {
         skipCache?: boolean;
+        skipParents?: boolean;
     }): Promise<AccessControlList | undefined>;
     /**
      * Deletes the ACL with the given identifier from the database, returning the document that was actually
@@ -77,9 +108,16 @@ export declare class ACLUtils {
      * actually belongs to the same physical connection this repo does. Reusing it directly used to throw
      * (Mongo) or silently target the wrong connection (SQL).
      *
+     * Pass `unlessProtected: true` to leave a code-defined ACL (see `isProtectedACL()`) in place, resolving to
+     * `undefined` as if there had been nothing to remove. `RepoUtils` uses this when cleaning up after a record, so a
+     * record that shares a class/route ACL's uid can never delete that ACL.
+     *
      * @param uid The unique identifier of the ACL to remove.
+     * @param options Set `unlessProtected: true` to never remove a code-defined ACL.
      */
-    removeACL(uid: string): Promise<AccessControlList | undefined>;
+    removeACL(uid: string, options?: {
+        unlessProtected?: boolean;
+    }): Promise<AccessControlList | undefined>;
     /**
      * Compares two ACLs to see if they have been modified and returns the total number of changes between them.
      *
@@ -106,14 +144,27 @@ export declare class ACLUtils {
      * need the entity-side write and this ACL save to stay consistent should register a compensating action
      * via `registerRollbackHook()`.
      *
+     * Pass `createOnly: true` to claim a brand new ACL: it is only ever inserted (at version `0`), never merged
+     * into or overwritten on top of an ACL that already exists at the same uid. If one already exists - including
+     * one a concurrent caller inserted first, caught by the ACL collection's unique key - an `IDENTIFIER_EXISTS`
+     * `ApiError` (400) is thrown instead. Used by `RepoUtils.create()` so that a create can never adopt (and grant
+     * its creator rights on) an ACL that belongs to some other record.
+     *
      * @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.
+     * normal optimistic-locking update semantics. Set `createOnly: true` to only ever insert a new ACL (see above).
      * @return Returns the ACL that was stored in the database.
      */
     saveACL(acl: AccessControlList, options?: {
         preserveVersion?: boolean;
+        createOnly?: boolean;
     }): Promise<AccessControlList | null>;
+    /**
+     * Implements `saveACL()`'s `createOnly` mode: inserts `acl` as a brand new version `0` document, refusing with
+     * `IDENTIFIER_EXISTS` if an ACL already exists at its uid (checked up front, and again via the unique key if a
+     * concurrent insert wins the race in between).
+     */
+    private insertNewACL;
     /**
      * 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
@@ -123,8 +174,15 @@ export declare class ACLUtils {
      * overrides. As the `default_<uid>` record is always overwritten with the lastest version of the code, any
      * user-defined changes made to it are lost on service restart.
      *
-     * @param defaultAcl
-     * @returns
+     * Both uids are reserved (see `isReservedUid()`), so no record can be created at, adopt or remove either ACL.
+     *
+     * Contract: when RBAC is enabled and `acl` is given, this either resolves to the user-editable ACL (whose `uid`
+     * is `acl.uid`) or throws; it never resolves to `null` then. A missing user-editable ACL (e.g. one deleted since
+     * the last start) is recreated, with no records, under `default_<uid>`. It resolves to `null` only when RBAC is
+     * disabled or no `acl` is given, and then stores nothing.
+     *
+     * @param acl The code-defined ACL to store.
+     * @returns The user-editable ACL, or `null` when RBAC is disabled or no ACL was given.
      */
     saveDefaultACL(acl: AccessControlList): Promise<AccessControlList | null>;
     /**
@@ -138,8 +196,11 @@ export declare class ACLUtils {
      * would issue overlapping commands against one session, which drivers reject or misorder.
      *
      * @param uids The unique identifiers of the ACLs to remove.
+     * @param options Set `unlessProtected: true` to never remove a code-defined ACL (see `removeACL()`).
      */
-    removeACLs(uids: string[]): Promise<AccessControlList[]>;
+    removeACLs(uids: string[], options?: {
+        unlessProtected?: boolean;
+    }): 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rapidrest/service-core",
-    "version": "2.0.0",
+    "version": "2.1.1",
     "description": "Provides all core functionality for RapidREST based backend services.",
     "repository": "https://github.com/rapidrest/service-core.git",
     "author": "RapidREST <rapidrests@gmail.com>",