@rapidmx/restapi 0.1.0

package/dist/lib/routes/BaseFolderRoute.js

@@ -0,0 +1,192 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiError } from "@rapidrest/core";
+import { ACLAction, ApiErrorMessages, ApiErrors, CRUDRoute, RouteDecorators, } from "@rapidrest/service-core";
+const { Get, Head, Param, Post, Query, Request, Response, User: AuthUser } = RouteDecorators;
+/**
+ * See the identical helper (and its rationale for being duplicated rather than shared via a `util/` module)
+ * on `BaseScopedChildRoute.ts`.
+ */
+function resolveEffectiveUser(user, query) {
+    if (user) {
+        return user;
+    }
+    const shareToken = query?.shareToken;
+    return typeof shareToken === "string" && shareToken.length > 0
+        ? ({ uid: shareToken, roles: [], scopes: [] })
+        : undefined;
+}
+/**
+ * Extends the standard `CRUDRoute` CRUD scaffolding for `Folder` with a hybrid permission model — `Folder` is
+ * one of the two entities in this library with a real per-record `AccessControlList` (the other is `Mailbox`;
+ * see the architecture note on `Message.mailboxUid` in `models/types.ts`), so most of `CRUDRoute`'s default
+ * behavior already works correctly and is left untouched here:
+ *
+ * - `findById`/`update`/`delete`/`truncate` rely on `Folder`'s own record-level ACL, which by default inherits
+ * (via `AccessControlList.parentUid`) from its owning `Mailbox`'s ACL — so anyone the mailbox is shared with
+ * automatically gets the same access to its folders, while a single folder (e.g. one Calendar) can still be
+ * shared more narrowly by adding records directly to *that folder's own* ACL instead. `RepoUtils.findOne()`/
+ * `update()`/`delete()` check the record's own resolved ACL chain directly (no class-level fast-fail), so
+ * this works correctly once the class-level grant is denied; `truncate()` skips its class-level check
+ * entirely whenever `recordACL` is `true` (verified by reading its source) and relies on per-record
+ * filtering instead, which is equally safe here for the same reason.
+ * - `find`/`count`/`exists` are overridden here, for the same reason every other collection-or-fast-fail-gated
+ * operation in this library is: `RepoUtils.find()`/`count()`/`exists()` all check the class-level ACL as an
+ * unconditional first gate — before any per-record narrowing, and even that later narrowing falls back to
+ * the class grant for a record with no caller-specific entry — so a per-record ACL alone can't safely narrow
+ * them once class-level access is granted to anyone. `find`/`count` take an explicit `mailboxUid` query
+ * parameter and check permission against it directly; `exists` fetches the specific folder first (bypassing
+ * ACL) and then checks permission against *that folder's own* uid (i.e. its real resolved ACL chain), same
+ * as `findById` does implicitly.
+ * - `create` is also overridden, for a different reason: it seeds the new folder's ACL with `parentUid` set to
+ * the owning mailbox's ACL uid, which is what wires up the inheritance described above — this can't be done
+ * generically by `RepoUtils.create()`'s own default (it would parent to the `Folder` class ACL instead, which
+ * is deny-all and grants nothing) — and, since a folder doesn't exist yet at create time, permission is
+ * checked against the target `mailboxUid` from the request body instead. It also publishes a live-update
+ * notification (see `push/MailPushRoute.ts`) to the owning mailbox's channel, so a webmail client subscribed
+ * to a mailbox sees new folders appear without polling.
+ *
+ * `find`/`count`/`exists` also resolve an unauthenticated caller's `?shareToken=` query param via the local
+ * `resolveEffectiveUser()` helper below (see `BaseScopedChildRoute`'s doc comment for the full explanation of
+ * the mechanism this is one half of).
+ *
+ * KNOWN LIMITATIONS:
+ * - `update`/`delete` (folder rename/move/removal) do NOT publish a live-update notification, unlike every
+ * mutation on the folder-scoped entities in `BaseScopedChildRoute`. Overriding them here purely to add a
+ * notify call would mean re-implementing (and re-testing) the exact ACL-delegation behavior this class's own
+ * doc comment above is careful to leave untouched by relying on `CRUDRoute`'s defaults — a real gap, but a
+ * deliberate one given how comparatively rare and low-urgency folder structural changes are next to new-mail
+ * delivery, matching this library's existing "pragmatic subset, not full fidelity" scope elsewhere.
+ * - `findById` (also left on `CRUDRoute`'s default) does NOT resolve `?shareToken=` — a share link's token
+ * grants read access to the folder's *children* (e.g. its `CalendarEvent`s, via `BaseScopedChildRoute`), not
+ * to fetching the `Folder` record itself by id. A client wanting the calendar's display name alongside its
+ * events would need that carried elsewhere (e.g. denormalized onto `CalendarShareLink`), not fetched via this
+ * route with a token.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class BaseFolderRoute extends CRUDRoute {
+    async count(params, query, res, user) {
+        if (!this.repoUtils) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const mailboxUid = query?.mailboxUid;
+        if (!mailboxUid) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+        }
+        if (!(await this.aclUtils.hasPermission(resolveEffectiveUser(user, query), mailboxUid, ACLAction.COUNT))) {
+            return res.status(200).setHeader("content-length", 0);
+        }
+        // `shareToken` is consumed above by `resolveEffectiveUser()` for permission resolution only - it names
+        // no field on `T`, so it must not be forwarded into the data filter below (SQL: an unknown-column
+        // error; Mongo: a `$match` no real document ever satisfies, silently returning zero results either way).
+        const { shareToken: _shareToken, ...filterQuery } = query ?? {};
+        const result = await this.repoUtils.count({ ...filterQuery, ...params }, { limit: query?.limit, page: query?.page, version: query?.version, user, ignoreACL: true });
+        return res.status(200).setHeader("content-length", result);
+    }
+    async create(obj, req, user) {
+        if (!this.repoUtils) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const objs = Array.isArray(obj) ? obj : [obj];
+        const results = [];
+        for (const raw of objs) {
+            const mailboxUid = raw.mailboxUid;
+            if (!mailboxUid || !(await this.aclUtils.hasPermission(user, mailboxUid, ACLAction.CREATE))) {
+                throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
+            }
+            const instance = this.repoUtils.instantiateObject(raw);
+            const created = await this.repoUtils.create(instance, {
+                user,
+                ignoreACL: true,
+                acl: { uid: instance.uid, parentUid: mailboxUid, records: [] },
+            });
+            this.notificationUtils?.sendMessage(mailboxUid, this.modelClass.name, "create", created);
+            results.push(created);
+        }
+        return Array.isArray(obj) ? results : results[0];
+    }
+    async find(params, query, user) {
+        if (!this.repoUtils) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const mailboxUid = query?.mailboxUid;
+        if (!mailboxUid) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+        }
+        if (!(await this.aclUtils.hasPermission(resolveEffectiveUser(user, query), mailboxUid, ACLAction.LIST))) {
+            return [];
+        }
+        // See the identical `shareToken` exclusion (and its rationale) in `count()` above.
+        const { shareToken: _shareToken, ...filterQuery } = query ?? {};
+        return await this.repoUtils.find({ ...filterQuery, ...params }, { limit: query?.limit, page: query?.page, version: query?.version, user, ignoreACL: true });
+    }
+    async exists(id, query, res, user) {
+        if (!this.repoUtils) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const existing = await this.repoUtils.findOne(id, {
+            version: query?.version,
+            includeDeleted: query?.deleted === true || query?.deleted === "true",
+            ignoreACL: true,
+        });
+        const permitted = existing
+            ? await this.aclUtils.hasPermission(resolveEffectiveUser(user, query), existing.uid, ACLAction.EXISTS)
+            : false;
+        return permitted
+            ? res.status(200).setHeader("content-length", 1)
+            : res.status(404).setHeader("content-length", 0);
+    }
+}
+__decorate([
+    Head(),
+    __param(0, Param()),
+    __param(1, Query()),
+    __param(2, Response),
+    __param(3, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseFolderRoute.prototype, "count", null);
+__decorate([
+    Post(),
+    __param(1, Request),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseFolderRoute.prototype, "create", null);
+__decorate([
+    Get(),
+    __param(0, Param()),
+    __param(1, Query()),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseFolderRoute.prototype, "find", null);
+__decorate([
+    Head("/:id"),
+    __param(0, Param("id")),
+    __param(1, Query()),
+    __param(2, Response),
+    __param(3, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseFolderRoute.prototype, "exists", null);
+//# sourceMappingURL=BaseFolderRoute.js.map

package/dist/lib/routes/BaseFolderRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseFolderRoute.js","sourceRoot":"","sources":["../../../src/routes/BaseFolderRoute.ts"],"names":[],"mappings":"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"}

package/dist/lib/routes/BaseMailIngestRoute.js

@@ -0,0 +1,179 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import * as crypto from "crypto";
+import { ApiError, ObjectDecorators } from "@rapidrest/core";
+import { ApiErrorMessages, ApiErrors, DocDecorators, RepoUtils, RouteDecorators, } from "@rapidrest/service-core";
+import { IngestStatus } from "../models/types.js";
+const { Config, Inject, Logger } = ObjectDecorators;
+const { Description, Summary } = DocDecorators;
+const { Get, Post, Query, Request, Response } = RouteDecorators;
+/**
+ * Implements the `MTAIngestAdapter` HTTP contract (see `transport/MTAIngestAdapter.ts`) that the deployment's
+ * MTA (Postfix, Haraka, ...) integrates against to hand accepted internet mail to this library. Both endpoints
+ * are internal-only — never exposed to the public internet — and gated by a shared bearer secret rather than
+ * ordinary user JWT auth, since the caller is the MTA process, not an end user.
+ *
+ * This class is DB-agnostic; `mailboxClass`/`ingestQueueClass` are supplied by the Mongo/SQL concrete
+ * subclasses (`MailIngestRouteMongo`/`MailIngestRouteSQL`), following the same pattern
+ * `DefaultAccounts`/`DefaultAccountsMongo` use for a background service spanning multiple entity types.
+ *
+ * !!Note!! that, like `BasePushRoute`/`BaseStatusRoute`, this class is not automatically registered with a
+ * server — the consuming application must apply `@Route("/internal/mta")` to its own subclass. The
+ * `MTAIngestAdapter` doc comment's `GET /internal/mta/resolve`/`POST /internal/mta/deliver` paths assume that
+ * exact base path is used; if a deployment mounts it elsewhere, its MTA content-filter/lookup configuration
+ * must be updated to match.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class BaseMailIngestRoute {
+    /**
+     * Builds the query value used to match `Mailbox.aliasAddresses` against the given address. MongoDB's
+     * implicit array-element equality lets a plain value match "array contains" directly, so the default here
+     * is a no-op passthrough. `MailIngestRouteSQL` overrides this: the SQL backend stores `aliasAddresses` as a
+     * serialized `simple-json` column, where a plain equality filter compares against the whole serialized
+     * string and never matches a single element.
+     */
+    aliasQueryValue(address) {
+        return address;
+    }
+    async init() {
+        if (!this.mailboxRepo) {
+            this.mailboxRepo = await this._objectFactory.newInstance(RepoUtils, {
+                name: this.mailboxClass.name,
+                args: [this.mailboxClass],
+            });
+        }
+        if (!this.ingestQueueRepo) {
+            this.ingestQueueRepo = await this._objectFactory.newInstance(RepoUtils, {
+                name: this.ingestQueueClass.name,
+                args: [this.ingestQueueClass],
+            });
+        }
+    }
+    /**
+     * Verifies the caller presented the configured internal bearer secret. Deliberately not `@Auth(["jwt"])` —
+     * the caller is the local MTA process, not an end user with a JWT. Throws `403` if no secret is configured
+     * at all (fail closed, never fail open into an unauthenticated internal endpoint).
+     */
+    authorizeInternalCaller(req) {
+        const header = req.headers["authorization"];
+        const presented = (Array.isArray(header) ? header[0] : header)?.replace(/^Bearer\s+/i, "") ?? "";
+        const expected = this.ingestSecret ?? "";
+        const presentedBuf = Buffer.from(presented);
+        const expectedBuf = Buffer.from(expected);
+        const authorized = expected.length > 0 &&
+            presentedBuf.length === expectedBuf.length &&
+            crypto.timingSafeEqual(presentedBuf, expectedBuf);
+        if (!authorized) {
+            throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
+        }
+    }
+    async resolve(rcpt, req, res) {
+        this.authorizeInternalCaller(req);
+        await this.init();
+        if (!rcpt) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+        }
+        const address = rcpt.trim().toLowerCase();
+        const [byPrimary, byAlias] = await Promise.all([
+            this.mailboxRepo.find({ primarySmtpAddress: address }, { ignoreACL: true, limit: 1 }),
+            this.mailboxRepo.find({ aliasAddresses: this.aliasQueryValue(address) }, { ignoreACL: true, limit: 1 }),
+        ]);
+        return byPrimary.length > 0 || byAlias.length > 0 ? res.status(200) : res.status(404);
+    }
+    async deliver(req, res) {
+        this.authorizeInternalCaller(req);
+        await this.init();
+        if (!this.blobStore) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const envelopeFrom = firstHeader(req, "x-envelope-from") ?? "";
+        const envelopeToHeader = firstHeader(req, "x-envelope-to");
+        const envelopeTo = envelopeToHeader ? envelopeToHeader.split(",").map((a) => a.trim()) : [];
+        const raw = req.rawBody;
+        if (!raw || raw.length === 0 || envelopeTo.length === 0) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+        }
+        // A single SMTP transaction can carry more than one RCPT TO — resolve and stage one IngestQueueEntry
+        // per addressed mailbox so `ScanQueueJob` delivers independently to each, and one unknown/unresolvable
+        // recipient in the batch doesn't block delivery to the others.
+        const results = [];
+        for (const rcpt of envelopeTo) {
+            const address = rcpt.trim().toLowerCase();
+            const mailboxes = await this.mailboxRepo.find({ primarySmtpAddress: address }, { ignoreACL: true, limit: 1 });
+            const mailbox = mailboxes[0] ??
+                (await this.mailboxRepo.find({ aliasAddresses: this.aliasQueryValue(address) }, { ignoreACL: true, limit: 1 }))[0];
+            if (!mailbox) {
+                this.logger?.warn(`MailIngestRoute: dropping delivery for unresolvable recipient '${address}'.`);
+                results.push({ rcpt: address, queued: false });
+                continue;
+            }
+            const rawBlobKey = `ingest/${crypto.randomUUID()}`;
+            await this.blobStore.put(rawBlobKey, raw, { contentType: "message/rfc822" });
+            await this.ingestQueueRepo.create(new this.ingestQueueClass({
+                mailboxUid: mailbox.uid,
+                envelopeFrom,
+                envelopeTo: [address],
+                rawBlobKey,
+                status: IngestStatus.PENDING,
+            }), { ignoreACL: true });
+            results.push({ rcpt: address, queued: true });
+        }
+        res.status(202).json({ results });
+        return res;
+    }
+}
+__decorate([
+    Inject("BlobStore"),
+    __metadata("design:type", Object)
+], BaseMailIngestRoute.prototype, "blobStore", void 0);
+__decorate([
+    Config("mail:transport:ingest:secret"),
+    __metadata("design:type", String)
+], BaseMailIngestRoute.prototype, "ingestSecret", void 0);
+__decorate([
+    Logger,
+    __metadata("design:type", Object)
+], BaseMailIngestRoute.prototype, "logger", void 0);
+__decorate([
+    Summary("Resolve recipient"),
+    Description("Called by the MTA's recipient-validation hook before accepting a message. Responds 200 if a mailbox " +
+        "exists for the given address, 404 otherwise."),
+    Get("/resolve"),
+    __param(0, Query("rcpt")),
+    __param(1, Request),
+    __param(2, Response),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseMailIngestRoute.prototype, "resolve", null);
+__decorate([
+    Summary("Deliver message"),
+    Description("Called by the MTA's content-filter once a message has been accepted. Persists the raw message and " +
+        "enqueues it for scanning/delivery, then returns immediately."),
+    Post("/deliver"),
+    __param(0, Request),
+    __param(1, Response),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseMailIngestRoute.prototype, "deliver", null);
+function firstHeader(req, name) {
+    const value = req.headers[name];
+    return Array.isArray(value) ? value[0] : value;
+}
+//# sourceMappingURL=BaseMailIngestRoute.js.map

package/dist/lib/routes/BaseMailIngestRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseMailIngestRoute.js","sourceRoot":"","sources":["../../../src/routes/BaseMailIngestRoute.ts"],"names":[],"mappings":"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"}

package/dist/lib/routes/BaseMailboxRoute.js

@@ -0,0 +1,187 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiError, ObjectDecorators, UserUtils } from "@rapidrest/core";
+import { ACLAction, ApiErrorMessages, ApiErrors, CRUDRoute, RouteDecorators } from "@rapidrest/service-core";
+const { Param, Query, Request, Response, User: AuthUser } = RouteDecorators;
+const { Config } = ObjectDecorators;
+/**
+ * Extends the standard `CRUDRoute` CRUD scaffolding for `Mailbox` with ACL-driven `find`/`count` overrides,
+ * plus a `create` override that bypasses the ACL system entirely. `Mailbox` has a real per-record
+ * `AccessControlList` (`@Protect(..., true)`; see the architecture note on `Message.mailboxUid`), whose
+ * class-level ACL denies EVERY action to non-trusted callers, including `CREATE`.
+ *
+ * `create` is deliberately NOT gated by the class-level ACL at all (unlike every other action): provisioning a
+ * brand-new mailbox is a pure self-service action (any authenticated user may create their own) with no parent
+ * resource to check permission against — `RepoUtils.create()`'s own automatic owner-grant logic is what
+ * actually scopes the new mailbox to its creator, not a class-level check. A class-level `CREATE` grant to
+ * `.*` was tried first and found to leak: every mailbox's own ACL falls back to that SAME class ACL as its
+ * parent whenever a caller has no mailbox-specific record, so *any* authenticated user calling
+ * `ACLUtils.hasPermission(user, someOtherMailboxUid, CREATE)` (e.g. `BaseFolderRoute.create()` checking
+ * permission to create a folder *in* that mailbox) would incorrectly pass too. Denying `CREATE` at the class
+ * level entirely, and having this route check only `user` truthiness before bypassing ACL, closes that leak.
+ *
+ * A non-trusted caller's `ownerUserUid` is always forced to their own uid, discarding whatever the client
+ * sent — self-service creation can only ever create a mailbox *for yourself*. Only a trusted caller may create
+ * a mailbox with a different (or no) `ownerUserUid` — the latter is a true ownerless "shared mailbox" (the
+ * Exchange concept, e.g. `support@example.com`) with no single owner, only delegates added afterward via
+ * `BaseACLRoute` (`@rapidrest/service-core`). `RepoUtils.create()`'s automatic owner-grant is already
+ * conditioned on the creator lacking a trusted role, so a trusted caller creating an ownerless mailbox does
+ * not, on its own, leave behind a stray self-grant for the admin who happened to create it.
+ *
+ * `find`/`count` still need overriding despite the real per-record ACL: `RepoUtils.find()`/`count()` both
+ * check the class-level ACL as an unconditional first gate *before* any per-record narrowing, and even that
+ * later per-record narrowing falls back to the class grant for a record with no caller-specific entry —
+ * verified by reading their source. Rather than the old ownership-only (`ownerUserUid: user.uid`) scoping,
+ * these now query for every mailbox uid the caller has *any* ACL grant on — owned, shared-with-them as a
+ * delegate, or (for a trusted caller) every mailbox unfiltered — via `findAccessibleMailboxUids()`, backed by
+ * the exact same `AccessControlList` model `BaseACLRoute` exposes as CRUD (no new API surface). `exists`
+ * doesn't need this treatment: it fetches the specific record first (bypassing ACL) and then checks
+ * permission against *that record's own* uid via `ACLUtils.hasPermission`, which already resolves ownership,
+ * delegate shares, and trusted-role access correctly on its own — see `exists()` below, unchanged.
+ * `findById`/`update`/`delete` are unaffected for the same reason: `RepoUtils.findOne()`/`update()`/
+ * `delete()` check the *record's own* resolved ACL chain directly (no class-level fast-fail), so once the
+ * class-level grant is denied, that chain correctly resolves to "deny" for a caller with no grant and "allow"
+ * for the owner or any delegate — `CRUDRoute`'s default behavior for those already works correctly and is
+ * left untouched.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class BaseMailboxRoute extends CRUDRoute {
+    constructor() {
+        super(...arguments);
+        this.trustedRoles = ["admin"];
+    }
+    async create(obj, req, user) {
+        if (!user) {
+            throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
+        }
+        const isTrusted = UserUtils.hasRoles(user, this.trustedRoles);
+        const objs = Array.isArray(obj) ? obj : [obj];
+        if (!isTrusted) {
+            for (const o of objs) {
+                o.ownerUserUid = user.uid;
+            }
+        }
+        if (Array.isArray(obj)) {
+            return await this.doBulkCreate(objs, { req, user, ignoreACL: true });
+        }
+        return await this.doCreateObject(objs[0], { req, user, ignoreACL: true });
+    }
+    async find(params, query, user) {
+        if (!this.repoUtils || !user) {
+            return [];
+        }
+        const isTrusted = UserUtils.hasRoles(user, this.trustedRoles);
+        let scopedQuery = { ...query, ...params };
+        if (!isTrusted) {
+            const accessibleUids = await this.findAccessibleMailboxUids(user);
+            // An empty array must short-circuit rather than be passed through as a query filter value: the
+            // underlying query builder "zips" an array filter value's *last* element onto any query branch
+            // past its own length, so an empty array resolves to `undefined` for that field — which TypeORM
+            // (and this builder) treats as "no filter on this field", not "match nothing". Passing it through
+            // would incorrectly return every mailbox to a caller who is entitled to see none.
+            if (accessibleUids.length === 0) {
+                return [];
+            }
+            scopedQuery = { ...scopedQuery, uid: accessibleUids };
+        }
+        return await this.repoUtils.find(scopedQuery, {
+            limit: query?.limit,
+            page: query?.page,
+            version: query?.version,
+            user,
+            ignoreACL: true,
+        });
+    }
+    async count(params, query, res, user) {
+        if (!this.repoUtils || !user) {
+            return res.status(200).setHeader("content-length", 0);
+        }
+        const isTrusted = UserUtils.hasRoles(user, this.trustedRoles);
+        let scopedQuery = { ...query, ...params };
+        if (!isTrusted) {
+            const accessibleUids = await this.findAccessibleMailboxUids(user);
+            // See the identical short-circuit (and its rationale) in `find()` above.
+            if (accessibleUids.length === 0) {
+                return res.status(200).setHeader("content-length", 0);
+            }
+            scopedQuery = { ...scopedQuery, uid: accessibleUids };
+        }
+        const result = await this.repoUtils.count(scopedQuery, {
+            limit: query?.limit,
+            page: query?.page,
+            version: query?.version,
+            user,
+            ignoreACL: true,
+        });
+        return res.status(200).setHeader("content-length", result);
+    }
+    async exists(id, query, res, user) {
+        if (!this.repoUtils) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        const existing = await this.repoUtils.findOne(id, {
+            version: query?.version,
+            includeDeleted: query?.deleted === true || query?.deleted === "true",
+            ignoreACL: true,
+        });
+        const permitted = existing
+            ? await this.aclUtils.hasPermission(user, existing.uid, ACLAction.EXISTS)
+            : false;
+        return permitted
+            ? res.status(200).setHeader("content-length", 1)
+            : res.status(404).setHeader("content-length", 0);
+    }
+}
+__decorate([
+    Config("trusted_roles", ["admin"]),
+    __metadata("design:type", Array)
+], BaseMailboxRoute.prototype, "trustedRoles", void 0);
+__decorate([
+    __param(1, Request),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseMailboxRoute.prototype, "create", null);
+__decorate([
+    __param(0, Param()),
+    __param(1, Query()),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseMailboxRoute.prototype, "find", null);
+__decorate([
+    __param(0, Param()),
+    __param(1, Query()),
+    __param(2, Response),
+    __param(3, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseMailboxRoute.prototype, "count", null);
+__decorate([
+    __param(0, Param("id")),
+    __param(1, Query()),
+    __param(2, Response),
+    __param(3, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseMailboxRoute.prototype, "exists", null);
+//# sourceMappingURL=BaseMailboxRoute.js.map

package/dist/lib/routes/BaseMailboxRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseMailboxRoute.js","sourceRoot":"","sources":["../../../src/routes/BaseMailboxRoute.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,EAA6B,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAExI,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,eAAe,CAAC;AAC5E,MAAM,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,OAAgB,gBAAoC,SAAQ,SAAY;IAA9E;;QAEc,iBAAY,GAAa,CAAC,OAAO,CAAC,CAAC;IAyGjD,CAAC;IA9FgB,AAAN,KAAK,CAAC,MAAM,CAAC,GAAY,EAAW,GAAgB,EAAY,IAAc;QACjF,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,uBAAuB,EAAE,GAAG,EAAE,gBAAgB,CAAC,uBAAuB,CAAC,CAAC;QACzG,CAAC;QACD,MAAM,SAAS,GAAY,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACvE,MAAM,IAAI,GAAQ,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;gBAClB,CAAS,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC;YACvC,CAAC;QACL,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9E,CAAC;IAEY,AAAN,KAAK,CAAC,IAAI,CAAU,MAAW,EAAW,KAAU,EAAY,IAAc;QACjF,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,EAAE,CAAC;YAC3B,OAAO,EAAE,CAAC;QACd,CAAC;QACD,MAAM,SAAS,GAAY,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACvE,IAAI,WAAW,GAAQ,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,EAAE,CAAC;QAC/C,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,MAAM,cAAc,GAAa,MAAM,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC;YAC5E,+FAA+F;YAC/F,+FAA+F;YAC/F,gGAAgG;YAChG,kGAAkG;YAClG,kFAAkF;YAClF,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,CAAC;YACd,CAAC;YACD,WAAW,GAAG,EAAE,GAAG,WAAW,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC;QAC1D,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE;YAC1C,KAAK,EAAE,KAAK,EAAE,KAAK;YACnB,IAAI,EAAE,KAAK,EAAE,IAAI;YACjB,OAAO,EAAE,KAAK,EAAE,OAAO;YACvB,IAAI;YACJ,SAAS,EAAE,IAAI;SAClB,CAAC,CAAC;IACP,CAAC;IAEY,AAAN,KAAK,CAAC,KAAK,CACL,MAAW,EACX,KAAU,EACT,GAAiB,EACjB,IAAc;QAExB,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,EAAE,CAAC;YAC3B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,SAAS,GAAY,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACvE,IAAI,WAAW,GAAQ,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,EAAE,CAAC;QAC/C,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,MAAM,cAAc,GAAa,MAAM,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC;YAC5E,yEAAyE;YACzE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;YAC1D,CAAC;YACD,WAAW,GAAG,EAAE,GAAG,WAAW,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC;QAC1D,CAAC;QACD,MAAM,MAAM,GAAW,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE;YAC3D,KAAK,EAAE,KAAK,EAAE,KAAK;YACnB,IAAI,EAAE,KAAK,EAAE,IAAI;YACjB,OAAO,EAAE,KAAK,EAAE,OAAO;YACvB,IAAI;YACJ,SAAS,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;IAEY,AAAN,KAAK,CAAC,MAAM,CACF,EAAU,EACd,KAAU,EACT,GAAiB,EACjB,IAAc;QAExB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAClB,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,cAAc,EAAE,GAAG,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;QACvF,CAAC;QACD,MAAM,QAAQ,GAAkB,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE;YAC7D,OAAO,EAAE,KAAK,EAAE,OAAO;YACvB,cAAc,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,IAAI,KAAK,EAAE,OAAO,KAAK,MAAM;YACpE,SAAS,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,MAAM,SAAS,GAAY,QAAQ;YAC/B,CAAC,CAAC,MAAM,IAAI,CAAC,QAAS,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC;YAC1E,CAAC,CAAC,KAAK,CAAC;QACZ,OAAO,SAAS;YACZ,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC,CAAC;YAChD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;CACJ;AAzGa;IADT,MAAM,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,CAAC;;sDACU;AAWhC;IAAsB,WAAA,OAAO,CAAA;IAAoB,WAAA,QAAQ,CAAA;;;;8CAerE;AAEY;IAAM,WAAA,KAAK,EAAE,CAAA;IAAe,WAAA,KAAK,EAAE,CAAA;IAAc,WAAA,QAAQ,CAAA;;;;4CAyBrE;AAEY;IACR,WAAA,KAAK,EAAE,CAAA;IACP,WAAA,KAAK,EAAE,CAAA;IACP,WAAA,QAAQ,CAAA;IACR,WAAA,QAAQ,CAAA;;;;6CAuBZ;AAEY;IACR,WAAA,KAAK,CAAC,IAAI,CAAC,CAAA;IACX,WAAA,KAAK,EAAE,CAAA;IACP,WAAA,QAAQ,CAAA;IACR,WAAA,QAAQ,CAAA;;;;8CAgBZ"}