@rapidmx/meet-plugin 0.9.3 → 0.10.0

package/dist/lib/routes/BaseVideoMeetingRoute.js

@@ -19,6 +19,7 @@ import { ApiError, JWTUtils, ObjectDecorators } from "@rapidrest/core";
 import { ACLAction, ACLUtils, ApiErrorMessages, ApiErrors, DatabaseDecorators, DocDecorators, ModelUtils, RepoUtils, RouteDecorators, } from "@rapidrest/service-core";
 import { parseEffectsAssetsUrl } from "../util/EffectsUtils.js";
 import { buildIceServers } from "../util/IceServerUtils.js";
+import { hashPassword, verifyPassword as verifyPasswordHash } from "../util/PasswordUtils.js";
 import { buildBaseUrl } from "../util/PublicUrlUtils.js";
 import { RedisRelayBus } from "../util/RedisRelayBus.js";
 import { parseRelayEnabled, RELAY_LARGE_PAYLOAD_BYTES, RELAY_MAX_PAYLOAD_BYTES, RELAY_WS_MAX_BACKPRESSURE_BYTES, RelayHub, } from "../util/RelayHub.js";
@@ -46,6 +47,10 @@ const RELAY_WS_OPTIONS = WS_ROUTE_OPTIONS_SUPPORTED
 const MAX_TITLE_LENGTH = 200;
 const MAX_DISPLAY_NAME_LENGTH = 200;
 const MAX_EMAIL_LENGTH = 254;
+/** A generous ceiling, not a real policy - `hashPassword()`'s cost is already what actually limits how useful a
+ * very long guess is to an attacker. The lower bound (1) just rejects an accidentally-empty string; this feature
+ * has no stated complexity requirement. */
+const MAX_PASSWORD_LENGTH = 200;
 /** The most invitees a single private meeting may be created with - a defensive cap, not a real product limit
  * (this plugin's "full-mesh, up to 4-6 participants" design already makes a larger list impractical - see
  * `.claude/NOTES.md`), so a single request can't mint an unbounded number of invitee rows/tokens. */
@@ -256,6 +261,14 @@ export class BaseVideoMeetingRoute {
          * is what a route that was never initialized (a test's) keeps; `initRelayBus()` swaps in a hub on a Redis bus
          * when the deployment has one, before any socket can attach. Its socket caps are per server replica. */
         this.relayHub = new RelayHub({ maxPayloadBytes: RELAY_MESSAGE_LIMIT_BYTES, logger: { debug: (message) => this.logger.debug(message) } });
+        /** Every meeting's pending admission requests (`VideoMeeting.waitingRoomEnabled`), keyed by meeting uid then by
+         * the requester's own uid (real or freshly minted guest). In-memory and per server instance only - the same
+         * accepted tradeoff `relayHub` above already has: a restart drops anyone currently waiting, who simply
+         * requests again (see `VideoMeeting.waitingRoomEnabled`'s own doc comment). A request is removed once it
+         * resolves to a final answer and that answer has been polled (`pollAdmission()`) - an abandoned request (the
+         * requester never polls again) is never otherwise cleaned up; there is no GC job, matching this codebase's
+         * existing precedent for other never-expiring state (`Booking.manageToken`, `VideoMeetingInvitee.joinToken`). */
+        this.pendingAdmissions = new Map();
     }
     /**
      * Exposes the `@Model(...)`-supplied entity class as an instance property so `@Transactional()` on
@@ -367,6 +380,15 @@ export class BaseVideoMeetingRoute {
                 }
             }
         }
+        if (body.forceMuteOnJoin !== undefined && typeof body.forceMuteOnJoin !== "boolean") {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, "'forceMuteOnJoin' must be a boolean.");
+        }
+        if (body.password !== undefined && (typeof body.password !== "string" || body.password.length > MAX_PASSWORD_LENGTH)) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, `'password' must be a string of at most ${MAX_PASSWORD_LENGTH} characters.`);
+        }
+        if (body.waitingRoomEnabled !== undefined && typeof body.waitingRoomEnabled !== "boolean") {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, "'waitingRoomEnabled' must be a boolean.");
+        }
         return { mailboxUid: body.mailboxUid, visibility: body.visibility };
     }
     /** Parses a caller-supplied ISO timestamp, rejecting anything unparseable with a `400` - matches
@@ -394,6 +416,7 @@ export class BaseVideoMeetingRoute {
         // Same mint function - and so the same shape/entropy - as `publicSlug`: the two live in separate columns, so
         // the only collision namespace either shares is its own, exactly as in Phase 1.
         const organizerSlug = visibility === VideoMeetingVisibility.PRIVATE ? mintPublicSlug() : undefined;
+        const passwordHash = body.password ? await hashPassword(body.password) : undefined;
         // Constructed before `create()` is called (rather than inline) because its own, already-generated `uid`
         // (every `BaseEntity` mints one on construction) is what `acl.uid` below claims the meeting's own
         // per-record ACL under - mirroring `BaseFolderRoute.create()`'s identical `acl: { uid: instance.uid, ... }`
@@ -408,6 +431,9 @@ export class BaseVideoMeetingRoute {
             endTime,
             publicSlug,
             organizerSlug,
+            forceMuteOnJoin: body.forceMuteOnJoin,
+            passwordHash,
+            waitingRoomEnabled: body.waitingRoomEnabled,
         });
         const meeting = await this.meetingRepo.create(instance, {
             user: strippedUser,
@@ -476,6 +502,14 @@ export class BaseVideoMeetingRoute {
         const base = buildBaseUrl(this.publicUrl);
         return base ? `${base}/${tokenOrSlug}` : undefined;
     }
+    /** Never let the stored password hash itself reach a response, not even the meeting's own owner's - a hash
+     * leak invites offline brute-forcing for no benefit to the owner, who already knows the plaintext they set (or
+     * can simply set a new one if they forgot it). Applied everywhere a raw persisted entity would otherwise flow
+     * straight into a response: `create()`, `withJoinUrls()` (so `find()`/`findById()` inherit it too), `update()`. */
+    withoutPasswordHash(meeting) {
+        const { passwordHash: _passwordHash, ...rest } = meeting;
+        return rest;
+    }
     async create(rawBody, req, user) {
         await this.init();
         const { mailboxUid, visibility } = this.validateCreateBody(rawBody);
@@ -484,7 +518,7 @@ export class BaseVideoMeetingRoute {
         const endTime = this.requireOptionalDate(body.endTime, "endTime");
         await this.requireMailboxAccess(mailboxUid, user, ACLAction.CREATE);
         const { meeting, invitees } = await this.persistMeeting(mailboxUid, body, visibility, startTime, endTime, user);
-        const result = { meeting };
+        const result = { meeting: this.withoutPasswordHash(meeting) };
         if (visibility === VideoMeetingVisibility.PRIVATE) {
             result.invitees = invitees.map((invitee) => ({
                 uid: invitee.uid,
@@ -510,10 +544,11 @@ export class BaseVideoMeetingRoute {
      * 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.
+     * response-only. Also strips `passwordHash` (`withoutPasswordHash()`) - `find()`/`findById()` are this field's
+     * only other response paths besides `create()`/`update()`, which strip it themselves.
      */
     withJoinUrls(meeting) {
-        const result = { ...meeting };
+        const result = this.withoutPasswordHash({ ...meeting });
         if (meeting.organizerSlug) {
             result.organizerJoinUrl = this.joinUrl(meeting.organizerSlug);
         }
@@ -580,15 +615,42 @@ export class BaseVideoMeetingRoute {
             }
             patch.status = VideoMeetingStatus.CANCELLED;
         }
-        if (patch.title === undefined && patch.status === undefined) {
-            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, "Nothing to update: supply 'title' and/or 'status'.");
+        if (body?.forceMuteOnJoin !== undefined) {
+            if (typeof body.forceMuteOnJoin !== "boolean") {
+                throw new ApiError(ApiErrors.INVALID_REQUEST, 400, "'forceMuteOnJoin' must be a boolean.");
+            }
+            patch.forceMuteOnJoin = body.forceMuteOnJoin;
+        }
+        if (body?.password !== undefined) {
+            if (body.password === null) {
+                patch.passwordHash = null;
+            }
+            else if (typeof body.password !== "string" || !body.password || body.password.length > MAX_PASSWORD_LENGTH) {
+                throw new ApiError(ApiErrors.INVALID_REQUEST, 400, `'password' must be a non-empty string of at most ${MAX_PASSWORD_LENGTH} characters, or null to remove it.`);
+            }
+            else {
+                patch.passwordHash = await hashPassword(body.password);
+            }
+        }
+        if (body?.waitingRoomEnabled !== undefined) {
+            if (typeof body.waitingRoomEnabled !== "boolean") {
+                throw new ApiError(ApiErrors.INVALID_REQUEST, 400, "'waitingRoomEnabled' must be a boolean.");
+            }
+            patch.waitingRoomEnabled = body.waitingRoomEnabled;
+        }
+        if (patch.title === undefined &&
+            patch.status === undefined &&
+            patch.forceMuteOnJoin === undefined &&
+            patch.passwordHash === undefined &&
+            patch.waitingRoomEnabled === undefined) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, "Nothing to update: supply 'title', 'forceMuteOnJoin', 'password', 'waitingRoomEnabled' and/or 'status'.");
         }
         const strippedUser = stripTrustedRoles(user, this.trustedRoles);
         const updated = await this.meetingRepo.update(patch, meeting, { user: strippedUser, ignoreACL: true });
         if (patch.status === VideoMeetingStatus.CANCELLED) {
             await this.deleteAttendeeLinks(meeting, await this.findInvitees(meeting), strippedUser);
         }
-        return updated;
+        return this.withoutPasswordHash(updated);
     }
     async delete(id, user) {
         await this.init();
@@ -601,6 +663,39 @@ export class BaseVideoMeetingRoute {
         }
         await this.meetingRepo.delete(meeting.uid, { user: strippedUser, ignoreACL: true });
     }
+    async kick(id, uid, user) {
+        await this.init();
+        const meeting = await this.requireOwnedMeeting(id, user, ACLAction.UPDATE);
+        await this.revokeChannelGrant(meeting.uid, uid);
+    }
+    async listWaiting(id, user) {
+        await this.init();
+        const meeting = await this.requireOwnedMeeting(id, user, ACLAction.READ);
+        const pending = this.pendingAdmissions.get(meeting.uid);
+        if (!pending) {
+            return [];
+        }
+        return [...pending.entries()]
+            .filter(([, request]) => request.status === "pending")
+            .sort(([, a], [, b]) => a.requestedAt.getTime() - b.requestedAt.getTime())
+            .map(([uid, request]) => ({ uid, name: request.name, requestedAt: request.requestedAt.toISOString() }));
+    }
+    async admit(id, uid, user) {
+        await this.init();
+        const meeting = await this.requireOwnedMeeting(id, user, ACLAction.UPDATE);
+        const request = this.pendingAdmissions.get(meeting.uid)?.get(uid);
+        if (request) {
+            request.status = "admitted";
+        }
+    }
+    async deny(id, uid, user) {
+        await this.init();
+        const meeting = await this.requireOwnedMeeting(id, user, ACLAction.UPDATE);
+        const request = this.pendingAdmissions.get(meeting.uid)?.get(uid);
+        if (request) {
+            request.status = "denied";
+        }
+    }
     /**
      * 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
@@ -706,6 +801,33 @@ export class BaseVideoMeetingRoute {
             }
         }
     }
+    /**
+     * Removes `uid`'s `ACLRecord` from `meetingUid`'s own `AccessControlList`, if it has one - the mirror image of
+     * `ensureChannelGrant()`, used to enforce a kick (see `kick()`): once removed, `uid` can no longer subscribe to
+     * or publish on the meeting's `/push` channel, so even a client that ignores the cooperative `"kicked"` signal
+     * (`SignalMessage`'s doc comment) cannot keep participating. A no-op when `uid` holds no grant (already kicked,
+     * or never joined) or the meeting has no ACL, rather than an error - the caller wants "not able to rejoin",
+     * which is already true either way. Same optimistic-lock retry as `ensureChannelGrant()`, for the same reason:
+     * a concurrent joiner or the owner editing the ACL directly may save first.
+     */
+    async revokeChannelGrant(meetingUid, uid) {
+        for (let attempt = 0; attempt < GUEST_GRANT_MAX_ATTEMPTS; attempt++) {
+            const acl = await this.aclUtils.findACL(meetingUid, [], { skipCache: true, skipParents: true });
+            if (!acl || !acl.records.some((record) => record.userOrRoleId === uid)) {
+                return;
+            }
+            acl.records = acl.records.filter((record) => record.userOrRoleId !== uid);
+            try {
+                await this.aclUtils.saveACL(acl);
+                return;
+            }
+            catch (err) {
+                if (attempt === GUEST_GRANT_MAX_ATTEMPTS - 1 || !/must be of the same version/.test(err?.message ?? "")) {
+                    throw err;
+                }
+            }
+        }
+    }
     /**
      * 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
@@ -725,65 +847,166 @@ export class BaseVideoMeetingRoute {
         const token = JWTUtils.createTokenSync(guestAuthConfig, { uid: guestUid, roles: [], scopes: [] }, { sessionUid: crypto.randomUUID(), exp: Math.floor(expiresAt.getTime() / 1000) });
         return { guestUid, token, expiresAt };
     }
-    /** 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). */
-    async hostDisplayName(mailboxUid) {
+    /** The host mailbox's `displayName` and owning account uid, or both `undefined` when the mailbox has none (or no
+     * longer exists - an orphaned meeting should still be joinable, just without a host to show or grant controls
+     * to). One lookup for both fields, since `join()` needs them together. */
+    async hostInfo(mailboxUid) {
         const mailbox = await this.mailboxRepo.findOne(mailboxUid, { ignoreACL: true });
-        return mailbox?.displayName || undefined;
+        return { hostDisplayName: mailbox?.displayName || undefined, hostUid: mailbox?.ownerUserUid || undefined };
     }
-    async join(token, user) {
-        await this.init();
-        const { meeting, resolvedVia } = await this.requireMeetingByToken(token);
-        // An `organizerSlug` is not a credential of its own (unlike an invitee `joinToken` or a `publicSlug`): it
-        // only exists so the owner of a private meeting has something that resolves to it at all, since they are
-        // deliberately never one of its invitees. So it is gated here on BOTH conditions, before anything about
-        // the meeting is computed or returned: a real, already-authenticated identity (the same non-guest check
-        // the authenticated branch below uses - a returning guest presenting a prior join()'s guest JWT is not
-        // one), AND that identity actually holding READ on this meeting's own mailbox, with its trusted roles
-        // stripped first exactly as `requireMailboxAccess()` does. A failure answers the bare 404
-        // `requireMeetingByToken()` already throws for a token that matched nothing whatsoever - deliberately NOT
-        // `requireMailboxAccess()`'s 403, which would tell an anonymous prober that this slug named a real meeting.
-        // Nothing here changes how an invitee token or a publicSlug resolves.
-        if (resolvedVia === "organizerSlug") {
-            const isRealCaller = !!user && !user.uid.startsWith(GUEST_UID_PREFIX);
-            if (!isRealCaller || !(await this.aclUtils.hasPermission(stripTrustedRoles(user, this.trustedRoles), meeting.mailboxUid, ACLAction.READ))) {
-                throw new ApiError(ApiErrors.NOT_FOUND, 404, ApiErrorMessages.NOT_FOUND);
-            }
-        }
-        const relayEnabled = this.isRelayEnabled();
-        const effectsAssetsUrl = parseEffectsAssetsUrl(this.effectsAssetsUrlSetting);
-        const publicMeeting = {
+    /** The `PublicVideoMeeting` projection shared by `join()`'s two possible responses (granted or
+     * password-required) and `verifyPassword()`'s - computed once a token/slug has resolved, before either method
+     * decides what else (if anything) to grant. */
+    async buildPublicMeeting(meeting) {
+        const { hostDisplayName, hostUid } = await this.hostInfo(meeting.mailboxUid);
+        return {
             uid: meeting.uid,
             title: meeting.title,
             visibility: meeting.visibility,
             status: meeting.status,
-            hostDisplayName: await this.hostDisplayName(meeting.mailboxUid),
+            hostDisplayName,
+            hostUid,
+            forceMuteOnJoin: meeting.forceMuteOnJoin || undefined,
+            hasPassword: meeting.passwordHash ? true : undefined,
+            waitingRoomEnabled: meeting.waitingRoomEnabled || undefined,
         };
+    }
+    /**
+     * Enforces the organizer-slug-only authority check - see `join()`'s doc comment on why holding an
+     * `organizerSlug` is not, by itself, a credential. A no-op for the other two resolutions. Shared between
+     * `join()` and `verifyPassword()`, since either could in principle be called first for an organizer's own link
+     * (a password a host also set on their own meeting should never block them - this check already proves
+     * stronger authority than any password could add, which is exactly why both methods skip the password
+     * check entirely once this passes).
+     */
+    async requireOrganizerAuth(meeting, resolvedVia, user) {
+        if (resolvedVia !== "organizerSlug") {
+            return;
+        }
+        const isRealCaller = !!user && !user.uid.startsWith(GUEST_UID_PREFIX);
+        if (!isRealCaller || !(await this.aclUtils.hasPermission(stripTrustedRoles(user, this.trustedRoles), meeting.mailboxUid, ACLAction.READ))) {
+            throw new ApiError(ApiErrors.NOT_FOUND, 404, ApiErrorMessages.NOT_FOUND);
+        }
+    }
+    /**
+     * The actual grant for a *definite*, already-known identity: ICE servers and `READ`/`CREATE` on the meeting's
+     * channel. Shared by `completeJoin()` (which still has to decide whether that identity is the caller's own
+     * real uid or a freshly minted guest) and `pollAdmission()`'s admitted branch (whose identity was already
+     * fixed back when `requestAdmission()` filed it - polling must grant exactly that uid, never mint a different
+     * one, which is why this doesn't call `mintGuestToken()` itself). Never includes `token`/`expiresAt` - a fresh
+     * guest mint (when there is one) is the caller's job, since only `completeJoin()`'s anonymous branch needs it.
+     */
+    async grantJoin(meeting, publicMeeting, selfUid, authenticated) {
+        await this.ensureChannelGrant(meeting.uid, selfUid);
+        const relayEnabled = this.isRelayEnabled();
+        const effectsAssetsUrl = parseEffectsAssetsUrl(this.effectsAssetsUrlSetting);
         const iceServers = buildIceServers({
             url: this.turnUrl,
             username: this.turnUsername,
             credential: this.turnCredential,
             sharedSecret: this.turnSharedSecret,
         });
+        return { meeting: publicMeeting, iceServers, authenticated, selfUid, relayEnabled, ...(effectsAssetsUrl && { effectsAssetsUrl }) };
+    }
+    /**
+     * Grants the caller's own real uid, or a freshly minted guest identity - shared by `join()` (when neither a
+     * password nor a waiting room blocks it) and `verifyPassword()` (once both are satisfied, or were never
+     * required). Everything `join()`'s own doc comment says about the `authenticated`/`selfUid`/`token` shape
+     * applies here unchanged.
+     */
+    async completeJoin(meeting, publicMeeting, user) {
         // A real, already-authenticated RapidMX identity - never a guest uid from an earlier join() call
         // presenting its own guest JWT back (a guest uid is never a valid mailbox-owning identity anyway, so this
         // prefix check is a safe, cheap discriminator - see this class's doc comment and GUEST_UID_PREFIX).
         if (user && !user.uid.startsWith(GUEST_UID_PREFIX)) {
-            await this.ensureChannelGrant(meeting.uid, user.uid);
-            return { meeting: publicMeeting, iceServers, authenticated: true, selfUid: user.uid, relayEnabled, ...(effectsAssetsUrl && { effectsAssetsUrl }) };
+            return this.grantJoin(meeting, publicMeeting, user.uid, true);
         }
-        const { guestUid, token: guestToken, expiresAt } = this.mintGuestToken();
-        await this.ensureChannelGrant(meeting.uid, guestUid);
-        return {
-            meeting: publicMeeting,
-            iceServers,
-            authenticated: false,
-            selfUid: guestUid,
-            token: guestToken,
-            expiresAt: expiresAt.toISOString(),
-            relayEnabled,
-            ...(effectsAssetsUrl && { effectsAssetsUrl }),
-        };
+        const { guestUid, token, expiresAt } = this.mintGuestToken();
+        const granted = await this.grantJoin(meeting, publicMeeting, guestUid, false);
+        return { ...granted, token, expiresAt: expiresAt.toISOString() };
+    }
+    /**
+     * Files `name` as a pending admission for `meeting` under the caller's own identity - their real uid when
+     * already authenticated (never a guest uid - same `GUEST_UID_PREFIX` discriminator `completeJoin()` uses), or
+     * a freshly minted guest identity otherwise, exactly as `completeJoin()` would choose between the two. Grants
+     * nothing: `ensureChannelGrant()` runs only once `pollAdmission()` sees the host admitted this uid, which is
+     * the whole point of a waiting room. The caller gets back enough to identify themselves on every subsequent
+     * poll - their `selfUid`, and a guest's own `token` to poll with (an already-authenticated caller's existing
+     * session cookie already does that job, so none is minted for them).
+     */
+    requestAdmission(meeting, publicMeeting, user, name) {
+        const isRealCaller = !!user && !user.uid.startsWith(GUEST_UID_PREFIX);
+        if (isRealCaller) {
+            this.registerPendingAdmission(meeting.uid, user.uid, name);
+            return { meeting: publicMeeting, requiresAdmission: true, authenticated: true, selfUid: user.uid };
+        }
+        const { guestUid, token, expiresAt } = this.mintGuestToken();
+        this.registerPendingAdmission(meeting.uid, guestUid, name);
+        return { meeting: publicMeeting, requiresAdmission: true, authenticated: false, selfUid: guestUid, token, expiresAt: expiresAt.toISOString() };
+    }
+    /** Records (or overwrites, for a re-request under the same identity) one pending admission. */
+    registerPendingAdmission(meetingUid, uid, name) {
+        let pending = this.pendingAdmissions.get(meetingUid);
+        if (!pending) {
+            pending = new Map();
+            this.pendingAdmissions.set(meetingUid, pending);
+        }
+        pending.set(uid, { name, requestedAt: new Date(), status: "pending" });
+    }
+    async join(token, user) {
+        await this.init();
+        const { meeting, resolvedVia } = await this.requireMeetingByToken(token);
+        await this.requireOrganizerAuth(meeting, resolvedVia, user);
+        const publicMeeting = await this.buildPublicMeeting(meeting);
+        if (resolvedVia !== "organizerSlug") {
+            if (meeting.waitingRoomEnabled) {
+                return { meeting: publicMeeting, requiresAdmission: true };
+            }
+            if (meeting.passwordHash) {
+                return { meeting: publicMeeting, requiresPassword: true };
+            }
+        }
+        return this.completeJoin(meeting, publicMeeting, user);
+    }
+    async verifyPassword(token, body, user) {
+        await this.init();
+        const { meeting, resolvedVia } = await this.requireMeetingByToken(token);
+        await this.requireOrganizerAuth(meeting, resolvedVia, user);
+        const bypassed = resolvedVia === "organizerSlug";
+        if (!bypassed && meeting.passwordHash) {
+            if (typeof body?.password !== "string" || !(await verifyPasswordHash(body.password, meeting.passwordHash))) {
+                throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, "Incorrect password.");
+            }
+        }
+        const publicMeeting = await this.buildPublicMeeting(meeting);
+        if (!bypassed && meeting.waitingRoomEnabled) {
+            if (typeof body?.name !== "string" || !body.name.trim()) {
+                throw new ApiError(ApiErrors.INVALID_REQUEST, 400, "'name' is required to request admission.");
+            }
+            return this.requestAdmission(meeting, publicMeeting, user, body.name.trim());
+        }
+        return this.completeJoin(meeting, publicMeeting, user);
+    }
+    async pollAdmission(token, user) {
+        await this.init();
+        const { meeting } = await this.requireMeetingByToken(token);
+        const pending = this.pendingAdmissions.get(meeting.uid)?.get(user.uid);
+        if (!pending) {
+            throw new ApiError(ApiErrors.NOT_FOUND, 404, ApiErrorMessages.NOT_FOUND);
+        }
+        if (pending.status === "denied") {
+            this.pendingAdmissions.get(meeting.uid)?.delete(user.uid);
+            throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, "The host denied your request to join.");
+        }
+        const publicMeeting = await this.buildPublicMeeting(meeting);
+        if (pending.status === "pending") {
+            return { meeting: publicMeeting, requiresAdmission: true, authenticated: !user.uid.startsWith(GUEST_UID_PREFIX), selfUid: user.uid };
+        }
+        this.pendingAdmissions.get(meeting.uid)?.delete(user.uid);
+        // Grants exactly the uid that was admitted - never completeJoin(), which would mint a brand new guest
+        // identity instead of recognizing this poller as the one requestAdmission() already filed (see
+        // grantJoin()'s own doc comment).
+        return this.grantJoin(meeting, publicMeeting, user.uid, !user.uid.startsWith(GUEST_UID_PREFIX));
     }
     /** Whether the WebSocket media relay is enabled - `mail:videoconf:relay:enabled`, see `parseRelayEnabled()`. */
     isRelayEnabled() {
@@ -1004,9 +1227,12 @@ __decorate([
     __metadata("design:returntype", Promise)
 ], BaseVideoMeetingRoute.prototype, "findById", null);
 __decorate([
-    Summary("Updates a video meeting's title, or cancels it."),
-    Description("Deliberately minimal for Phase 1: only 'title' and cancellation ('status': 'cancelled') may be changed. " +
-        "Requires UPDATE on the meeting's owning mailbox."),
+    Summary("Updates a video meeting's title, force-mute-on-join/password/waiting-room settings, or cancels it."),
+    Description("Deliberately minimal for Phase 1: only 'title', 'forceMuteOnJoin', 'password', 'waitingRoomEnabled' and " +
+        "cancellation ('status': 'cancelled') may be changed. 'password' hashes before storage; 'null' " +
+        "removes password protection entirely, a non-empty string sets/replaces it. Requires UPDATE on the " +
+        "meeting's owning mailbox. The response never carries the stored password hash, same as every other " +
+        "response that includes a meeting."),
     Put("/:id"),
     __param(0, Param("id")),
     __param(2, AuthUser),
@@ -1027,6 +1253,66 @@ __decorate([
     __metadata("design:paramtypes", [String, Object]),
     __metadata("design:returntype", Promise)
 ], BaseVideoMeetingRoute.prototype, "delete", null);
+__decorate([
+    Summary("Removes a participant from a video meeting."),
+    Description("Revokes 'uid's grant on the meeting's own push channel (revokeChannelGrant()), so they can no longer " +
+        "subscribe to or publish on it - and therefore can no longer signal or relay media, even if their " +
+        "client ignores the cooperative 'kicked' signal the host's own UI also sends over the mesh (see " +
+        "SignalMessage's doc comment for why that signal alone isn't enforcement). A no-op if 'uid' holds no " +
+        "grant (already removed, or never joined). Requires UPDATE on the meeting's owning mailbox. " +
+        "Known limitation: this revokes the one grant 'uid' currently holds, not the token/slug they used to " +
+        "get it - a removed guest who reloads the same join link is minted a brand new guest uid and " +
+        "re-granted by join() exactly as any other first-time joiner would be, and a removed real caller who " +
+        "still holds mailbox READ is re-granted their own uid back the same way. An actual ban (rejecting a " +
+        "specific identity's future joins, not just today's connection) is a larger feature - new state " +
+        "tracking who was removed and join()/ensureChannelGrant() consulting it - out of scope here."),
+    Post("/:id/kick/:uid"),
+    __param(0, Param("id")),
+    __param(1, Param("uid")),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "kick", null);
+__decorate([
+    Summary("Lists a video meeting's pending admission requests."),
+    Description("Returns everyone currently waiting to be admitted (VideoMeeting.waitingRoomEnabled), oldest first - " +
+        "never anyone already admitted or denied, since pendingAdmissions drops a request once it reaches a " +
+        "final answer and the requester has polled it. Requires READ on the meeting's owning mailbox."),
+    Get("/:id/waiting"),
+    __param(0, Param("id")),
+    __param(1, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "listWaiting", null);
+__decorate([
+    Summary("Admits a pending admission request."),
+    Description("Marks 'uid's pending request admitted - their next GET /join/:token/status poll completes the join and " +
+        "grants their channel access, exactly as join() itself would for a meeting with no waiting room. A " +
+        "no-op (not an error) if 'uid' has no pending request (already resolved, or never requested at all) - " +
+        "there is nothing left to admit either way. Requires UPDATE on the meeting's owning mailbox."),
+    Post("/:id/admit/:uid"),
+    __param(0, Param("id")),
+    __param(1, Param("uid")),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "admit", null);
+__decorate([
+    Summary("Denies a pending admission request."),
+    Description("Marks 'uid's pending request denied - their next GET /join/:token/status poll answers 403 and removes " +
+        "the record, so a second poll (or a fresh admission request under the same identity) starts clean. " +
+        "A no-op if 'uid' has no pending request. Requires UPDATE on the meeting's owning mailbox."),
+    Post("/:id/deny/:uid"),
+    __param(0, Param("id")),
+    __param(1, Param("uid")),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "deny", null);
 __decorate([
     Summary("Joins a video meeting."),
     Description("Resolves an invitee's join token or a public meeting's slug. If the caller already presents a valid " +
@@ -1038,7 +1324,12 @@ __decorate([
         "to exchange WebRTC signaling messages. Requires no authentication beyond the token itself; a " +
         "stale/unknown token answers 404. The one exception is a private meeting's organizerSlug, which is " +
         "never an anonymous surface: it additionally requires an already-authenticated caller holding READ on " +
-        "the meeting's owning mailbox, and answers the very same 404 for anyone else."),
+        "the meeting's owning mailbox, and answers the very same 404 for anyone else. If the meeting requires " +
+        "admission (a waiting room - see VideoMeeting.waitingRoomEnabled) and wasn't resolved via " +
+        "organizerSlug, returns { meeting, requiresAdmission: true } instead - even when a password is also " +
+        "required, since both are requested together on POST /join/:token/verify's one combined screen. " +
+        "Otherwise, if just a password is required, returns { meeting, requiresPassword: true }. Either way " +
+        "nothing is granted until POST /join/:token/verify succeeds."),
     RateLimit(),
     Get("/join/:token"),
     __param(0, Param("token")),
@@ -1047,6 +1338,44 @@ __decorate([
     __metadata("design:paramtypes", [String, Object]),
     __metadata("design:returntype", Promise)
 ], BaseVideoMeetingRoute.prototype, "join", null);
+__decorate([
+    Summary("Verifies a video meeting's join password and/or files an admission request."),
+    Description("Checks 'password' against the meeting's own stored hash when one is required - 403 for a wrong or " +
+        "missing password, never revealing how close a guess was. Once satisfied (or when no password is " +
+        "required at all): if the meeting also has a waiting room (VideoMeeting.waitingRoomEnabled), requires " +
+        "'name' and files a pending admission instead of granting anything, returning " +
+        "{ meeting, requiresAdmission: true, selfUid, token? } - poll GET /join/:token/status, authenticated " +
+        "as that identity, to learn whether the host has responded. Otherwise completes the join exactly as " +
+        "GET /join/:token would for a meeting with neither requirement - the same grant, the same response " +
+        "shape. Calling this via the organizer's own slug bypasses both checks unconditionally, matching GET " +
+        "/join/:token's own posture. Rate-limited, like GET /join/:token, since this is the one endpoint a " +
+        "brute-force password guesser would actually hit repeatedly."),
+    RateLimit(),
+    Post("/join/:token/verify"),
+    __param(0, Param("token")),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "verifyPassword", null);
+__decorate([
+    Summary("Polls the status of a pending admission request."),
+    Description("Authenticated as the identity verifyPassword() (or a previous poll) returned - the cookie session for " +
+        "an already-authenticated real caller, or the 'Authorization: jwt <token>' header for a guest's own " +
+        "minted token. Returns a granted VideoMeetingJoinResult once the host has admitted the request (the " +
+        "same shape and grant GET /join/:token itself would give), re-returns " +
+        "{ requiresAdmission: true } while the host hasn't responded yet, and 403 once the host has denied " +
+        "it (the pending record is then gone - polling again answers 404, the same as never having requested " +
+        "admission at all). 404 if this identity never requested admission to this meeting (or already " +
+        "polled past a final answer)."),
+    Auth(["jwt"]),
+    Get("/join/:token/status"),
+    __param(0, Param("token")),
+    __param(1, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "pollAdmission", null);
 __decorate([
     Summary("Relays media over a WebSocket."),
     Description("The last-resort media path for a participant whose network blocks both a direct WebRTC connection and TURN: " +