@rapidmx/meet-plugin 0.1.0

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

@@ -0,0 +1,131 @@
+import type { BaseEntity } from "@rapidrest/service-core";
+/** Whether a `VideoMeeting` is joinable only by its explicitly invited `VideoMeetingInvitee`s (each with their
+ * own unguessable `joinToken`), or by anyone holding the meeting's single `publicSlug` link. */
+export declare enum VideoMeetingVisibility {
+    PRIVATE = "private",
+    PUBLIC = "public"
+}
+/** The lifecycle of a `VideoMeeting`. Deliberately minimal for Phase 1 - `ACTIVE` and `ENDED` are not yet set by
+ * any code in this package (no signaling event currently transitions a meeting automatically); they exist so the
+ * shape doesn't need to change once a later phase starts using them. `CANCELLED` is the one transition
+ * `BaseVideoMeetingRoute.update()` actually performs today. */
+export declare enum VideoMeetingStatus {
+    SCHEDULED = "scheduled",
+    ACTIVE = "active",
+    ENDED = "ended",
+    CANCELLED = "cancelled"
+}
+/**
+ * A WebRTC video meeting owned by a `Mailbox` - joinable directly via this plugin's own API (for now; a later
+ * phase wires an "Add video conferencing" hook into calendar event compose, see `calendarEventUid` below) or by
+ * anyone holding a valid link (a private invitee's `joinToken`, or a public meeting's `publicSlug`).
+ *
+ * Anonymous access to this entity is NOT granted through the `AccessControlList`'s class-level default (see
+ * `@Protect`'s deny-all `records` on the concrete `VideoMeetingMongo`/`VideoMeetingSQL`) - `BaseVideoMeetingRoute`
+ * does its own authorization: the owner's routes check `ACLUtils.hasPermission()` against the meeting's
+ * `mailboxUid` (with the caller's trusted roles stripped first - see `util/RouteAccessUtils.ts`), and the
+ * anonymous `join()` route resolves a caller by `joinToken`/`publicSlug` directly, the same posture
+ * `booking-plugin`'s `BaseBookingRoute` documents for `Booking`/`BookingType`.
+ *
+ * Unlike `Booking`, this entity DOES get its own per-record `AccessControlList` (`@Protect`'s `recordACL: true`) -
+ * its own `uid` doubles as its `/push` signaling channel (see `BaseVideoMeetingRoute`'s class doc comment), and a
+ * `/push` channel is authorized purely by whether a per-channel `AccessControlList` document grants the caller an
+ * action on it (`ACLUtils.hasPermission(user, channelUid, action)`); there would be no such document to check
+ * against at all without `recordACL: true`. Creating a meeting's own ACL with `parentUid` set to its `mailboxUid`
+ * (see `BaseVideoMeetingRoute.create()`) lets a mailbox owner/delegate reach it exactly as they reach any other
+ * mailbox-scoped record, through the normal ACL parent-chain inheritance - no separate mechanism is needed for
+ * the owner's own push access, only for a guest's (see `join()`'s doc comment).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface VideoMeeting extends BaseEntity {
+    /** The unique identifier of the `Mailbox` that owns this meeting. Managing it (create/list/delete/cancel) is
+     * permission-checked against this mailbox's `AccessControlList`, the same as every other mailbox-scoped child
+     * entity - see the architecture note on `Message.mailboxUid` in `@rapidmx/restapi`'s `models/types.ts`. */
+    mailboxUid: string;
+    /** The unique identifier of the `CalendarEvent` this meeting was minted for, if any. Optional in Phase 1: a
+     * meeting can exist with no calendar event at all (created directly through this plugin's own API, e.g. for
+     * testing); a later phase wires an "Add video conferencing" control into calendar event compose that sets
+     * this when it mints a meeting for a real invite. */
+    calendarEventUid?: string;
+    title: string;
+    visibility: VideoMeetingVisibility;
+    /**
+     * The public join link's unique identifier, set only when `visibility` is `PUBLIC`. Random rather than
+     * name-derived (unlike `booking-plugin`'s human-chosen `BookingType.slug`) - see `util/TokenUtils.ts`'s
+     * `mintPublicSlug()` doc comment for the exact shape/entropy and why.
+     *
+     * The concrete `VideoMeetingMongo`/`VideoMeetingSQL` classes index this unique **globally**, matching exactly
+     * what `BaseVideoMeetingRoute.join()`'s public URL actually looks up (`/join/:token`, not
+     * `/join/:mailboxUid/:token` - the lookup carries no mailbox segment at all). An initial design considered
+     * scoping the database constraint to the owning mailbox instead (mirroring `BookingType.slug`'s own scope,
+     * for consistency with `booking-plugin`'s precedent - see this package's `.claude/NOTES.md`'s Phase 1 entry),
+     * but a per-mailbox *compound* sparse index doesn't actually work: it still indexes a document carrying at
+     * least one of its keys, and every row has `mailboxUid`, so two *private* meetings in one mailbox (both
+     * missing `publicSlug`) would collide on `(mailboxUid, null)` and the second could never be created - a real
+     * bug, not just a weaker-than-intended constraint, found and fixed before release. A single-field sparse
+     * index skips a document missing the field entirely, which both fixes that bug and happens to match the
+     * lookup's real (global) scope exactly - see `organizerSlug` below, which hit the identical pitfall.
+     */
+    publicSlug?: string;
+    /**
+     * The organizer's own join link identifier, minted only for a `PRIVATE` meeting, at creation. It exists solely
+     * so the meeting's organizer has *some* token `BaseVideoMeetingRoute.requireMeetingByToken()` can resolve to
+     * their own meeting: a private meeting's only other resolvable credentials are its invitees' `joinToken`s, and
+     * the calendar integration that mints a meeting per event deliberately builds `invitees` from the event's
+     * attendees *excluding* the organizer (the organizer manages the meeting through ownership, not as a guest), so
+     * without this the organizer of their own private meeting would have no link that resolves at all.
+     *
+     * **Unlike `publicSlug`, holding this value is not by itself a credential.** Resolving a token through this
+     * field never grants anonymous or guest access: `BaseVideoMeetingRoute.join()` additionally requires a real,
+     * already-authenticated (non-guest) caller who holds `READ` on the meeting's own `mailboxUid`, and answers the
+     * same bare `404` as an entirely unknown token for anyone else - see that method's doc comment. The value is
+     * unguessable all the same (the same `mintPublicSlug()` shape/entropy as `publicSlug`, stored in its own
+     * column), but that unguessability is defense in depth here, not the authorization itself.
+     *
+     * A meeting's `visibility` never changes after creation, and neither does this field. It is never set for a
+     * `PUBLIC` meeting. It is, however, genuinely optional even for a private one: a private meeting minted through
+     * `createSingleInviteeVideoMeeting()` (`util/BookingIntegrationUtils.ts` - `booking-plugin`'s in-process
+     * integration, whose meetings are managed from the booking flow and have no organizer to hand a link to) has
+     * none, so code must check for its presence rather than infer it from `visibility` alone.
+     *
+     * The concrete `VideoMeetingMongo`/`VideoMeetingSQL` classes index this unique globally, single-field sparse -
+     * the same shape `publicSlug`'s own index was corrected to (see above); this field never had the per-mailbox
+     * version to begin with, having been added after that pitfall was already found.
+     */
+    organizerSlug?: string;
+    status: VideoMeetingStatus;
+    /** Informational only in Phase 1 - not used for any availability or conflict checking (a video meeting has no
+     * concept of "busy" the way a `Booking` does). */
+    startTime?: Date;
+    /** Informational only in Phase 1 - see `startTime`. */
+    endTime?: Date;
+}
+/**
+ * One invited participant of a `PRIVATE` `VideoMeeting`, minted server-side by `BaseVideoMeetingRoute.create()` -
+ * one row per `{ email, displayName? }` the owner supplied at creation time. `joinToken` is this invitee's only
+ * credential (mirroring `Booking.manageToken` exactly - see `util/TokenUtils.ts`'s `mintJoinToken()`): possession
+ * of the link is what lets an anonymous invitee reach `BaseVideoMeetingRoute.join()`, never an
+ * `AccessControlList` grant of its own (this entity's class ACL is deny-all, like `Booking`'s - see
+ * `@Protect` on the concrete `VideoMeetingInviteeMongo`/`VideoMeetingInviteeSQL`).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface VideoMeetingInvitee extends BaseEntity {
+    /** The unique identifier of the `VideoMeeting` this invitee belongs to. */
+    meetingUid: string;
+    /**
+     * The unique identifier of the host `Mailbox`, denormalized from the meeting - mirroring `Booking.mailboxUid`'s
+     * own doc comment exactly: this lets `ErasureExecutionJob` find and purge every invitee of an erased mailbox's
+     * meetings by `mailboxUid` alone (the `@MailboxScopedData()` contract), without a join back through
+     * `VideoMeeting`, and lets a host's invitees be listed without one either.
+     */
+    mailboxUid: string;
+    /** The invitee's email address, normalized to lowercase. */
+    email: string;
+    displayName?: string;
+    /** The unguessable token embedded in this invitee's join link, minted server-side (32 random bytes) and
+     * immutable thereafter. Like `Booking.manageToken`, this has no expiry and no GC job of its own - see
+     * `BaseVideoMeetingRoute`'s class doc comment for the same documented tradeoff. */
+    joinToken: string;
+}

package/dist/types/mongo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This plugin's `./mongo` entry point: exactly the classes a server host loads for a Mongo deployment - the video
+ * meeting models and the route mounted at `/api/mail/video-meetings`. Anything else exported here would be
+ * registered by the host too, so the abstract route and utilities stay in the package root.
+ */
+export { VideoMeetingMongo } from "./models/mongo/VideoMeetingMongo.js";
+export { VideoMeetingInviteeMongo } from "./models/mongo/VideoMeetingInviteeMongo.js";
+export { VideoMeetingRouteMongo } from "./routes/mongo/VideoMeetingRouteMongo.js";

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

@@ -0,0 +1,368 @@
+import { type JWTUser } from "@rapidrest/core";
+import { HttpRequest } from "@rapidrest/service-core";
+import { Mailbox } from "@rapidmx/restapi";
+import { IceServerConfig } from "../util/IceServerUtils.js";
+import { VideoMeeting, VideoMeetingInvitee, VideoMeetingStatus, VideoMeetingVisibility } from "../models/types.js";
+/** How long a guest JWT minted by `join()` remains valid for. Four hours comfortably covers a realistic call's
+ * length (including some run-over) without a guest's session dying mid-call; there is no refresh mechanism in
+ * Phase 1, so a guest who is still on the call past this needs to re-open the join link. */
+export declare const GUEST_JWT_TTL_SECONDS: number;
+/** The fixed prefix every guest uid `mintGuestToken()` mints starts with - also how `join()` tells a genuine,
+ * already-authenticated RapidMX identity apart from a returning guest presenting a JWT from an earlier `join()`
+ * call (see `join()`'s doc comment): a guest uid is never a real mailbox-owning identity, so this prefix is a safe,
+ * cheap discriminator with no separate "is this a guest" flag needed anywhere. */
+export declare const GUEST_UID_PREFIX = "guest:";
+/** The request body accepted by `create()`. */
+export interface CreateVideoMeetingBody {
+    mailboxUid?: string;
+    title?: string;
+    visibility?: string;
+    /** The `CalendarEvent` this meeting is being minted for, if any - see `VideoMeeting.calendarEventUid`. */
+    calendarEventUid?: string;
+    startTime?: string;
+    endTime?: string;
+    /** Required (and non-empty), only when `visibility` is `"private"`. */
+    invitees?: {
+        email?: string;
+        displayName?: string;
+    }[];
+}
+/** One invitee of a newly created private meeting, as returned by `create()` - everything a caller needs to build
+ * that invitee's own share of the calendar invite (Phase 3's job). */
+export interface VideoMeetingInviteeJoinInfo {
+    uid: string;
+    email: string;
+    displayName?: string;
+    /** `undefined` when `mail:videoconf:public_url` isn't configured - see `BaseVideoMeetingRoute`'s class doc
+     * comment. */
+    joinUrl?: string;
+}
+/** `create()`'s response: the persisted meeting, plus whatever link(s) a caller needs to invite people to it. */
+export interface VideoMeetingCreateResult<T extends VideoMeeting = VideoMeeting> {
+    meeting: T;
+    /** Present (possibly empty only if `invitees` validation somehow let that through - it never does, see
+     * `validateCreateBody()`) exactly when `meeting.visibility` is `"private"`. */
+    invitees?: VideoMeetingInviteeJoinInfo[];
+    /** Present exactly when `meeting.visibility` is `"public"`; `undefined` within that case only when
+     * `mail:videoconf:public_url` isn't configured. */
+    publicJoinUrl?: string;
+    /** The organizer's own join link, present exactly when `meeting.organizerSlug` is set - i.e. for every private
+     * meeting this route creates, *alongside* `invitees` rather than instead of it (`undefined` within that case
+     * only when `mail:videoconf:public_url` isn't configured). The organizer of a private meeting is deliberately
+     * never one of its own `invitees`, so this is the only link that resolves to the meeting for them - see
+     * `VideoMeeting.organizerSlug` and `join()`'s doc comment for why holding it is not by itself a credential. */
+    organizerJoinUrl?: string;
+}
+/** Which field of which row `requireMeetingByToken()` matched the caller's token against - `join()` authorizes each
+ * differently, so the resolution is returned explicitly rather than re-derived by comparing strings afterwards. */
+export type VideoMeetingTokenResolution = "invitee" | "publicSlug" | "organizerSlug";
+/** The public projection of a `VideoMeeting`, as returned to an anonymous joiner - deliberately narrow: a guest
+ * never sees `mailboxUid`, `calendarEventUid` or any other internal identifier. */
+export interface PublicVideoMeeting {
+    uid: string;
+    title: string;
+    visibility: VideoMeetingVisibility;
+    status: VideoMeetingStatus;
+    /** The host mailbox's `displayName`, when it has one. */
+    hostDisplayName?: string;
+}
+/**
+ * `join()`'s response.
+ *
+ * **`authenticated`/`selfUid`/`token` - reading this shape correctly.** A caller who already presented a valid
+ * session for a real, non-guest RapidMX identity (see `join()`'s doc comment for exactly how that's told apart
+ * from a returning guest) gets `authenticated: true` and no `token`/`expiresAt` at all - there is no guest JWT to
+ * hand over, because the caller's own already-existing session cookie/header already authenticates `/push` for
+ * them, with zero new client-side auth handling. The frontend must not write any cookie in that case (doing so
+ * would be pointless at best, and at worst overwrite the caller's real cookie with... the value it already has).
+ * The common anonymous case (`authenticated: false`) is unchanged from Phase 1: `token`/`expiresAt` are present
+ * and the frontend applies `token` as the `jwt` cookie before connecting - see
+ * `apps/shared/push/GuestSignalingClient.ts`.
+ */
+export interface VideoMeetingJoinResult {
+    meeting: PublicVideoMeeting;
+    iceServers: IceServerConfig[];
+    /** `true` when the caller already presented a valid session for a real RapidMX identity when calling `join()`;
+     * `false` for the common anonymous case, where a fresh guest identity was just minted instead. */
+    authenticated: boolean;
+    /** The identity now holding `READ`/`CREATE` on the meeting's own push channel, and the uid the frontend's mesh
+     * connection manager (`apps/shared/webrtc/MeshConnectionManager.ts`) must identify itself as: the caller's own
+     * real uid when `authenticated` is `true`, otherwise the freshly minted synthetic `guest:<random>` uid `token`
+     * authenticates as. Always present - this replaces Phase 1's guest-only `guestUid` field now that the same
+     * grant-and-identify step also runs for a real, already-authenticated caller. */
+    selfUid: string;
+    /** A short-lived guest JWT, immediately usable against `/push` to subscribe to and publish on `meeting.uid` -
+     * and nothing else. Present only when `authenticated` is `false`; omitted entirely for an already-authenticated
+     * real caller, who has no guest token minted for them at all (see `join()`). See this class's doc comment. */
+    token?: string;
+    /** ISO 8601 instant `token` expires at. Present only when `authenticated` is `false`, exactly when `token`
+     * itself is. */
+    expiresAt?: string;
+}
+/**
+ * The owner's management of their own `VideoMeeting`s (JWT-authenticated, mailbox-ACL-checked exactly like any
+ * other mailbox-scoped entity - see `booking-plugin`'s `BaseBookingTypeRoute` for the same "must own or hold a
+ * grant on the mailbox" pattern this class hand-implements) and the anonymous `join()` endpoint a private
+ * invitee's `joinToken` or a public meeting's `publicSlug` resolves through.
+ *
+ * Like `BaseBookingRoute`, this is a standalone class, NOT a `CRUDRoute`/`BaseScopedChildRoute` subclass: `create()`'s
+ * response is not itself a bare `VideoMeeting` (it also carries invitee join links / the public join link, which the
+ * generic CRUD return type can't express), and `join()` is anonymous and token-resolved, the same shape of
+ * requirement that keeps `BaseBookingRoute` standalone. Every repo call passes `ignoreACL: true` because this class
+ * performs its own authorization: the owner-side methods check `ACLUtils.hasPermission()` against the meeting's
+ * `mailboxUid` with the caller's trusted roles stripped first (`util/RouteAccessUtils.ts` - see that module's doc
+ * comment for why: without it, `ACLUtils.hasPermission()`'s own "trusted users always have permission" rule would
+ * let an administrator read or manage a mailbox they hold no grant on, which is never true for mail here), and
+ * `join()` resolves an anonymous caller purely by the token/slug's own database match. Like `Booking`/`BookingType`,
+ * the concrete `VideoMeetingMongo`/`VideoMeetingSQL`/`VideoMeetingInviteeMongo`/`VideoMeetingInviteeSQL` classes carry
+ * an ordinary deny-all class ACL; `"anonymous"` is never granted an action anywhere.
+ *
+ * Like `BaseBookingRoute`/`BaseMailIngestRoute`/`BasePushRoute`, this class carries no `@Route`/`@ApiRoute` of its
+ * own - the consuming Mongo/SQL concrete subclass applies one (`mail/video-meetings`).
+ *
+ * ## Path shape
+ *
+ * `join()` lives at the literal `/join/:token` (not `/:token` at the root), the same reasoning `BaseBookingRoute`'s
+ * doc comment gives for its own `/manage/<token>` vs. `/:slug/slots` split: a bare `/:token` at the root would
+ * collide with (and make router registration order decide between) this class's own `/:id` owner routes.
+ *
+ * ## Why `VideoMeeting` gets its own per-record `AccessControlList`
+ *
+ * Unlike `Booking`, `VideoMeeting.uid` doubles as a `/push` signaling channel (see `.claude/NOTES.md`'s "Signaling"
+ * design note): SDP offers/answers and ICE candidates are ordinary `NotificationUtils.sendMessage()` payloads
+ * published to it, exactly as `MailPushRoute`'s doc comment describes for a `Mailbox`/`Folder` channel. A `/push`
+ * channel is authorized purely by `ACLUtils.hasPermission(user, channelUid, action)` against a per-record
+ * `AccessControlList` document keyed by that exact uid - there being no such document at all (the case for
+ * `Booking`, whose `@Protect` sets `recordACL: false`) makes `hasPermission()` always answer `false`. So
+ * `VideoMeetingMongo`/`VideoMeetingSQL` set `recordACL: true`, and `create()` below claims that per-record ACL
+ * with `parentUid` set to the meeting's own `mailboxUid` (mirroring `BaseFolderRoute`'s identical `acl: { uid,
+ * parentUid: mailboxUid, records: [] }` pattern) - which is also what lets a mailbox owner/delegate reach the
+ * meeting (and its channel) through the ordinary ACL parent-chain, with no extra mechanism needed on top of what
+ * `RepoUtils.create()`'s automatic per-record ACL claim already does (it grants the creator full rights on the
+ * fresh ACL - see `RepoUtils.claimRecordACL()`).
+ *
+ * ## The channel-ACL-grant mechanism
+ *
+ * An anonymous guest holds no `AccessControlList` grant of their own and has no `JWTUser` to authenticate `/push`
+ * with in the first place - `join()` therefore does two things together: it mints a short-lived, scope-limited
+ * guest JWT (`mintGuestToken()`: a synthetic `guest:<random>` uid, no roles, `GUEST_JWT_TTL_SECONDS` expiry, real and
+ * verifiable since it's signed with the same `auth` config every other token is), and it adds an explicit
+ * `ACLRecord` for that exact uid onto the meeting's own `AccessControlList` (`ensureChannelGrant()`), granting
+ * `READ` (so `BasePushRoute`'s SUBSCRIBE succeeds) and `CREATE` (so a publish does - see `MailPushRoute`'s doc
+ * comment: "publishing to a channel needs CREATE on it as an ordinary user would"). The grant is scoped to exactly
+ * that one meeting's uid, nothing else - the same "possession of a link is the credential" pattern
+ * `BaseBookingRoute.requireBookingByToken()`/`resolveEffectiveUser()`'s `share:<token>` identity already establish
+ * elsewhere in this codebase, extended one step further because signaling needs a channel *subscription*, not just
+ * a stateless REST call.
+ *
+ * **Known limitation, documented rather than silently assumed away**: because each `join()` call for an anonymous
+ * caller mints a *fresh* random guest uid (so simultaneous participants of one shared link are distinguishable from
+ * each other in the signaling channel), each such join adds one more `ACLRecord` to the meeting's own ACL document,
+ * and nothing in Phase 1 ever removes one. A meeting joined many times over its lifetime accumulates unused records;
+ * there is no GC job, matching this codebase's own precedent for `Booking.manageToken` (documented as never
+ * expiring, no GC job either). Since the guest JWTs themselves expire, an accumulated record is inert (unusable)
+ * well before it becomes a real concern - a cleanup pass is a reasonable thing for a later phase to add, not a
+ * Phase 1 requirement. An already-authenticated real caller (see below) is granted their own stable uid instead, so
+ * repeated joins by the same real identity never add more than the one record `ensureChannelGrant()`'s own
+ * idempotency check already collapses them to.
+ *
+ * ## Real, already-authenticated callers (the browser-session-collision fix)
+ *
+ * `join()` also accepts an optional `@AuthUser`: whatever `req.user` the framework's own `JWTStrategy` already
+ * populated from the caller's existing `Authorization` header or `jwt` cookie, exactly like every other
+ * authenticated-optional endpoint in this codebase's family (e.g. `BaseScopedChildRoute.resolveEffectiveUser()`'s
+ * "prefer the real authenticated user, fall back to the anonymous token" precedent). This matters because a
+ * logged-in RapidMX user's browser already carries a real, `HttpOnly` `jwt` session cookie for this origin - a
+ * cookie `apps/shared/push/GuestSignalingClient.ts` cannot overwrite with a guest token even if `join()` minted one
+ * (browsers refuse to let a script override an `HttpOnly` cookie of the same name), so a guest-only `join()` would
+ * leave that browser's `/push` WebSocket authenticating as the real session while the meeting's ACL only names a
+ * synthetic guest uid - the subscribe is simply, safely refused, and the real user could never actually join.
+ *
+ * The fix: when `user` is present and is a *real* identity - not a guest uid from a previous `join()` call, told
+ * apart by the `GUEST_UID_PREFIX` a guest uid always starts with and a real, mailbox-owning identity never can -
+ * `join()` grants `user.uid` itself (not a synthetic one) `READ`/`CREATE` on the meeting's channel via
+ * `ensureChannelGrant()`, mints no guest JWT at all, and returns `authenticated: true` with `selfUid: user.uid`. The
+ * caller's own already-existing session cookie now already authenticates `/push` for them with zero new
+ * client-side auth handling - the frontend must not write a cookie of its own in this case (see
+ * `VideoMeetingJoinResult`'s doc comment). When `user` is absent (the common, true-anonymous case - no existing
+ * session at all), behavior is exactly Phase 1's: a fresh guest identity is minted and granted instead.
+ *
+ * ## The organizer's own slug (`VideoMeeting.organizerSlug`)
+ *
+ * The fix above lets a real, already-authenticated caller join *if they already hold something that resolves to the
+ * meeting*. The organizer of their own private meeting does not: the calendar integration that mints a meeting per
+ * event builds `invitees` from the event's attendees **excluding the organizer** (who manages the meeting through
+ * ownership, not as a guest), and `publicSlug` is minted only for a public meeting - so the one person who owns the
+ * meeting had no token `requireMeetingByToken()` could resolve for them at all. `persistMeeting()` therefore also
+ * mints an `organizerSlug` for every private meeting, `create()` returns it as `organizerJoinUrl` alongside the
+ * per-invitee links, and `findById()` returns the same link for a meeting loaded later.
+ *
+ * **This does not widen the `"private"` invariant by one caller.** The other two resolutions are credentials in
+ * themselves - possession of an invitee `joinToken` or a `publicSlug` is exactly what authorizes the join, by
+ * design. An `organizerSlug` is not: `requireMeetingByToken()` reports *which* field resolved the match, and for
+ * `"organizerSlug"` `join()` requires, before computing or returning anything about the meeting, both that the
+ * caller is a real already-authenticated identity (the same non-guest `GUEST_UID_PREFIX` check as above, so a
+ * returning guest presenting a prior `join()`'s own guest JWT never qualifies) and that this identity holds `READ`
+ * on the meeting's own `mailboxUid` - the very same `ACLUtils.hasPermission()` call, trusted roles stripped, that
+ * `requireMailboxAccess()` makes for every owner-side route, so a trusted administrator with no explicit grant is
+ * refused here exactly as they are there. Every caller who fails either condition - a true anonymous stranger, a
+ * returning guest, or a real but unrelated logged-in user - gets the identical bare `404` an entirely unknown token
+ * gets, never a `403`: this class never leaks whether a token almost-matched something, and an
+ * organizer-slug-shaped probe must be indistinguishable from a slug naming nothing at all. A caller who satisfies
+ * both proceeds through exactly the authenticated branch described above, with no new response field.
+ *
+ * ## Recovering a join link on a later read (`find()`/`findById()`, Phase 4)
+ *
+ * `create()`'s response computes `organizerJoinUrl`/`publicJoinUrl` inline, once, from the slug it just minted -
+ * fine for the moment of creation, but Phase 4's settings page (`apps/settings-video-conferencing`) needs a
+ * meeting's own persistent link on every later page load too, not only the one response `create()` ever sent (a
+ * user's "personal room", by this codebase's Phase 4 convention, is simply their oldest non-cancelled `PUBLIC`
+ * meeting - see `.claude/NOTES.md`'s Phase 4 entry for why no new field/route was needed to name it as such). Since
+ * a plain `RepoUtils.find()`/`findOne()` returns only the persisted slug columns, `find()` and `findById()` both
+ * now run every loaded meeting through `withJoinUrls()` - the exact same computation `create()` already did,
+ * applied uniformly on read instead of only once on write.
+ *
+ * ## Other known limitations
+ *
+ * **`VideoMeetingInvitee.joinToken` never expires** and has no GC job - identical tradeoff to `Booking.manageToken`.
+ *
+ * **`VideoMeeting.publicSlug` is only uniqueness-checked within its own mailbox** by the database, while `join()`'s
+ * lookup is global (the public join URL carries no mailbox segment) - see the `VideoMeeting.publicSlug` doc comment
+ * for the full reasoning; a cross-mailbox collision is not actually prevented, only made astronomically unlikely by
+ * the slug's own entropy. `VideoMeeting.organizerSlug` has the same shape and entropy but is indexed unique
+ * *globally*, which is exactly the scope its own lookup uses - see its doc comment for why a per-mailbox compound
+ * index cannot work for a field only half the rows carry. Less rides on it either way: resolving through it grants
+ * nothing by itself, so an unlucky collision there would cost a caller a `404`, never access.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class BaseVideoMeetingRoute<VM extends VideoMeeting, VMI extends VideoMeetingInvitee, M extends Mailbox> {
+    protected abstract meetingClass: any;
+    protected abstract inviteeClass: any;
+    protected abstract mailboxClass: any;
+    private _objectFactory?;
+    private meetingRepo?;
+    private inviteeRepo?;
+    private mailboxRepo?;
+    private aclUtils?;
+    private trustedRoles;
+    /** The `auth` config every other JWT in this deployment is signed/verified with - used by `mintGuestToken()` to
+     * mint a guest's own, short-lived token with the exact same signature the framework's `JWTStrategy` verifies. */
+    private authConfig;
+    /** The externally reachable base URL of the public join pages, used to build the invite links `create()`
+     * returns. Same single-value-config pattern as `mail:booking:public_url`/`mail:autodiscover:public_url`; when
+     * unset (or unsafe - see `buildBaseUrl()`) a join link is simply omitted rather than returning a broken one. */
+    private publicUrl;
+    private turnUrl;
+    private turnUsername;
+    private turnCredential;
+    private turnSharedSecret;
+    private logger;
+    /**
+     * Exposes the `@Model(...)`-supplied entity class as an instance property so `@Transactional()` on
+     * `persistMeeting()` can resolve which datasource to open a transaction against - identical to
+     * `BaseBookingRoute`'s own `modelClass` getter, for the same reason (this class deliberately doesn't extend
+     * `ModelRoute`, which defines the same getter for its own subclasses).
+     */
+    get modelClass(): any;
+    private init;
+    /** Rejects a `403` unless `user` (with its trusted roles stripped - see `util/RouteAccessUtils.ts`) holds
+     * `action` on `mailboxUid`, by ownership or an explicit ACL grant. */
+    private requireMailboxAccess;
+    /** Loads the meeting `id` names, `404` if it doesn't exist, then enforces `requireMailboxAccess()` against its
+     * `mailboxUid`. Used by every owner-side method that acts on a single existing meeting. */
+    private requireOwnedMeeting;
+    /** Pure shape/format validation of `create()`'s body - independent of any permission check, matching
+     * `BaseBookingRoute.validateBook()`'s split between format checks (here) and business-rule checks (in the
+     * handler itself, which needs a DB round trip this does not). */
+    private validateCreateBody;
+    /** Parses a caller-supplied ISO timestamp, rejecting anything unparseable with a `400` - matches
+     * `BaseBookingRoute.requireDate()`. `startTime`/`endTime` are optional, so this is only called when present. */
+    private requireOptionalDate;
+    /**
+     * Writes the `VideoMeeting`/`VideoMeetingInvitee` rows for a new meeting. `@Transactional()` (resolving its
+     * datasource from the `@Model(...)` on the concrete subclass, via the `modelClass` getter above) makes every
+     * write atomic, matching `BaseBookingRoute.persistBooking()`'s identical reasoning.
+     */
+    protected persistMeeting(mailboxUid: string, body: CreateVideoMeetingBody, visibility: VideoMeetingVisibility, startTime: Date | undefined, endTime: Date | undefined, user: JWTUser | undefined): Promise<{
+        meeting: VM;
+        invitees: VMI[];
+    }>;
+    /** The join URL for a token/slug, or `undefined` when no public URL is configured - see this class's doc
+     * comment on `mail:videoconf:public_url`. */
+    private joinUrl;
+    create(rawBody: CreateVideoMeetingBody | undefined, req: HttpRequest, user?: JWTUser): Promise<VideoMeetingCreateResult<VM>>;
+    /**
+     * Adds `organizerJoinUrl`/`publicJoinUrl` (see `joinUrl()`) to a persisted meeting for a caller re-reading it
+     * later. `create()`'s own response computes the same links inline from values it just minted, but `find()`/
+     * `findById()` load the plain persisted entity, which carries only the slugs themselves - so a caller who
+     * didn't keep `create()`'s one-time response (e.g. this plugin's own settings page, reloaded after the meeting
+     * that IS a user's "personal room" - see `.claude/NOTES.md`'s Phase 4 entry - was created in an earlier visit)
+     * would otherwise have no way to recover a public meeting's shareable link, or a private meeting's organizer
+     * link, at all. Spreads rather than mutates: the loaded instance is the repo's own entity, and both fields are
+     * response-only.
+     */
+    private withJoinUrls;
+    find(mailboxUid: string | undefined, limit: string | undefined, page: string | undefined, user?: JWTUser): Promise<(VM & {
+        organizerJoinUrl?: string;
+        publicJoinUrl?: string;
+    })[]>;
+    findById(id: string, user?: JWTUser): Promise<VM & {
+        organizerJoinUrl?: string;
+        publicJoinUrl?: string;
+    }>;
+    update(id: string, body: {
+        title?: string;
+        status?: string;
+    } | undefined, user?: JWTUser): Promise<VM>;
+    delete(id: string, user?: JWTUser): Promise<void>;
+    /**
+     * Resolves `token` to the meeting it names, and to *how* it named it: an invitee's `joinToken` (43 base64url
+     * characters - `JOIN_TOKEN_PATTERN`), or one of the two 11-character slugs (`PUBLIC_SLUG_PATTERN`) - a public
+     * meeting's `publicSlug` or a private meeting's `organizerSlug`. The token and slug lengths never overlap (see
+     * `util/TokenUtils.ts`), so an invitee token is never tried as a slug or vice versa - unlike trying both in
+     * sequence, this can't accidentally treat one as the other just because the lookup that should have matched
+     * happened to miss. A stale/unknown/malformed/wrongly-shaped token, a cancelled meeting, or a meeting whose
+     * visibility no longer matches how the token was resolved (defense in depth - a meeting's `visibility` cannot
+     * actually change after creation) all answer identically: a plain `404`, matching
+     * `BaseBookingRoute.requireBookingByToken()`'s exact posture of never leaking whether a token almost-matched
+     * something.
+     *
+     * The two slug columns are disjoint by construction (`persistMeeting()` mints `publicSlug` only for a public
+     * meeting and `organizerSlug` only for a private one), so a slug-shaped token is looked up against `publicSlug`
+     * first - exactly Phase 1's lookup, with exactly Phase 1's outcome whenever it matches a row at all - and only
+     * a token that matches no `publicSlug` row is then looked up against `organizerSlug`.
+     *
+     * The resolution is returned alongside the meeting because `join()` authorizes the three cases differently: an
+     * invitee token and a `publicSlug` are each a self-contained credential ("possession of the link"), while an
+     * `organizerSlug` is not - see `join()`'s doc comment and `VideoMeeting.organizerSlug`.
+     */
+    private requireMeetingByToken;
+    /**
+     * Adds an `ACLRecord` granting `uid` `READ`/`CREATE` on `meetingUid`'s own `AccessControlList`, unless one
+     * already exists (idempotent - a retried/duplicate call for the same uid, guest or real, is a no-op). Retries a
+     * handful of times on an optimistic-lock conflict (`saveACL()`'s version check): a public meeting can be joined
+     * by several callers at once, each racing to add their own record to the very same ACL document, and a lost
+     * race must be retried against the freshly re-read version rather than surfaced to the caller as an error.
+     * Named generically (not `ensureGuestChannelGrant()`, its Phase 1 name) since `join()` now calls this for a
+     * real, already-authenticated caller's own uid too - see this class's doc comment on "Real, already-
+     * authenticated callers".
+     */
+    private ensureChannelGrant;
+    /**
+     * Mints a short-lived, scope-limited guest identity - see this class's doc comment on the channel-ACL-grant
+     * mechanism. Only called for the true-anonymous case (`join()`'s `user` is absent, or presents a prior guest
+     * uid rather than a real one). The deployment's real `auth` config normally carries its own `options.expiresIn`
+     * (every other token's session length), which `jsonwebtoken` refuses to combine with an explicit `exp` claim in
+     * the payload ("Bad 'options.expiresIn' option the payload already has an 'exp' property") - so this signs with
+     * a shallow copy of `authConfig` that omits `options.expiresIn`, letting the payload's own `exp` (this guest
+     * token's own, shorter `GUEST_JWT_TTL_SECONDS` lifetime) govern instead. Everything else about `authConfig` -
+     * the secret, the algorithm, `audience`/`issuer` - is unchanged, so this guest token verifies through the exact
+     * same `JWTStrategy` every other token does.
+     */
+    private mintGuestToken;
+    /** The host mailbox's `displayName`, or `undefined` when the mailbox has none (or no longer exists - an
+     * orphaned meeting should still be joinable, just without a host name to show). */
+    private hostDisplayName;
+    join(token: string, user?: JWTUser): Promise<VideoMeetingJoinResult>;
+}

package/dist/types/routes/mongo/VideoMeetingRouteMongo.d.ts

@@ -0,0 +1,10 @@
+import { MailboxMongo } from "@rapidmx/restapi/mongo";
+import { VideoMeetingMongo } from "../../models/mongo/VideoMeetingMongo.js";
+import { VideoMeetingInviteeMongo } from "../../models/mongo/VideoMeetingInviteeMongo.js";
+import { BaseVideoMeetingRoute } from "../BaseVideoMeetingRoute.js";
+/** The owner's video meeting management endpoints and the anonymous join endpoint (`/api/mail/video-meetings`). */
+export declare class VideoMeetingRouteMongo extends BaseVideoMeetingRoute<VideoMeetingMongo, VideoMeetingInviteeMongo, MailboxMongo> {
+    protected meetingClass: any;
+    protected inviteeClass: any;
+    protected mailboxClass: any;
+}

package/dist/types/routes/sql/VideoMeetingRouteSQL.d.ts

@@ -0,0 +1,10 @@
+import { MailboxSQL } from "@rapidmx/restapi/sql";
+import { VideoMeetingSQL } from "../../models/sql/VideoMeetingSQL.js";
+import { VideoMeetingInviteeSQL } from "../../models/sql/VideoMeetingInviteeSQL.js";
+import { BaseVideoMeetingRoute } from "../BaseVideoMeetingRoute.js";
+/** The owner's video meeting management endpoints and the anonymous join endpoint (`/api/mail/video-meetings`). */
+export declare class VideoMeetingRouteSQL extends BaseVideoMeetingRoute<VideoMeetingSQL, VideoMeetingInviteeSQL, MailboxSQL> {
+    protected meetingClass: any;
+    protected inviteeClass: any;
+    protected mailboxClass: any;
+}

package/dist/types/sql.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This plugin's `./sql` entry point: exactly the classes a server host loads for a SQL deployment - the video
+ * meeting models and the route mounted at `/api/mail/video-meetings`. Anything else exported here would be
+ * registered by the host too, so the abstract route and utilities stay in the package root.
+ */
+export { VideoMeetingSQL } from "./models/sql/VideoMeetingSQL.js";
+export { VideoMeetingInviteeSQL } from "./models/sql/VideoMeetingInviteeSQL.js";
+export { VideoMeetingRouteSQL } from "./routes/sql/VideoMeetingRouteSQL.js";

package/dist/types/util/BookingIntegrationUtils.d.ts

@@ -0,0 +1,51 @@
+import { ObjectFactory } from "@rapidrest/service-core";
+import { VideoMeeting, VideoMeetingInvitee } from "../models/types.js";
+/** The sole invitee `createSingleInviteeVideoMeeting()` mints a new private meeting for. */
+export interface SingleMeetingInvitee {
+    email: string;
+    displayName?: string;
+}
+/**
+ * **The integration surface other plugins call.** This is the one thing `@rapidmx/videoconf-plugin` exposes for
+ * another, independently-installed plugin to use in-process: mints a private `VideoMeeting` for exactly one
+ * invitee and returns just that invitee's join URL. `booking-plugin` is today's only caller - a video-location
+ * booking with no host-preset URL mints one of these automatically (the booker as the sole invitee, matching this
+ * plugin's own "one link per invitee" private-meeting design) - see that package's `BaseBookingRoute`/`.claude/
+ * NOTES.md` for the calling side, and this plugin's own `.claude/NOTES.md` for the design this integration was
+ * built against.
+ *
+ * This is deliberately the ONLY integration point this package exposes: everything else about `VideoMeeting`/
+ * `VideoMeetingInvitee` (routes, signaling, the join flow, cancellation, ...) is reached only through this
+ * package's own HTTP API. A caller never gets a `VideoMeeting`/`VideoMeetingInvitee` instance back, only the one
+ * value it actually needs, so this package stays free to change anything else about their shape without breaking
+ * a caller compiled against an older version.
+ *
+ * Mirrors `BaseVideoMeetingRoute.create()`'s own private-meeting-plus-single-invitee path exactly, including its
+ * `acl: { uid: instance.uid, parentUid: mailboxUid, records: [] }` claim (see that class's doc comment on why
+ * `VideoMeeting` needs its own per-record `AccessControlList`) - but skips everything about validating an HTTP
+ * request body or checking a caller's own permission on the mailbox: this is an in-process call from code that has
+ * already established both by its own means (e.g. `booking-plugin`'s already-authorized, already-validated
+ * booking flow).
+ *
+ * A caller-supplied `title`/`invitee.displayName` longer than this package's own route-level limits is silently
+ * truncated rather than rejected - there is no request here to answer with a `400`, and a slightly-shortened title
+ * is a far better outcome than throwing back into whatever the caller's own flow was doing. (`booking-plugin`'s own
+ * call site additionally wraps this whole function in a `try`/`catch` so even a genuine failure here - a database
+ * error, a stale/misconfigured deployment - never blocks the caller's own operation; see its doc comment.)
+ *
+ * @param objectFactory The caller's own `ObjectFactory` - used exactly as `BaseVideoMeetingRoute` uses its own, to
+ * build the repos this needs and to resolve `mail:videoconf:public_url`.
+ * @param meetingClass The concrete `VideoMeeting` model class for the caller's own backend (`VideoMeetingMongo`/
+ * `VideoMeetingSQL`, from this package's `./mongo`/`./sql` entry points) - this package has no notion of "Mongo" vs.
+ * "SQL" itself (see `BaseVideoMeetingRoute`'s identical `meetingClass` constructor parameter), so the caller
+ * supplies it, the same way `booking-plugin`'s own `BookingRouteMongo`/`BookingRouteSQL` supply their own concrete
+ * classes to `BaseBookingRoute`.
+ * @param inviteeClass The concrete `VideoMeetingInvitee` model class for the same backend.
+ * @param mailboxUid The mailbox the meeting is minted under - the caller's own already-authorized mailbox.
+ * @param title A short, human-readable meeting title (e.g. the caller's own meeting/event name).
+ * @param invitee The sole invitee of the new private meeting.
+ * @returns The invitee's join URL, or `undefined` when `mail:videoconf:public_url` isn't configured on this
+ * deployment - mirroring `VideoMeetingInviteeJoinInfo.joinUrl`'s identical semantics exactly. Never throws for
+ * that reason alone; a genuine failure (a bad `objectFactory`, a database error, ...) still propagates.
+ */
+export declare function createSingleInviteeVideoMeeting<VM extends VideoMeeting, VMI extends VideoMeetingInvitee>(objectFactory: ObjectFactory, meetingClass: new (...args: any[]) => VM, inviteeClass: new (...args: any[]) => VMI, mailboxUid: string, title: string, invitee: SingleMeetingInvitee): Promise<string | undefined>;