feat: add room permissions and ownership system (#150)

* feat: add room permissions and ownership system (#142)

Introduce three-tier role system (owner, facilitator, participant) with
four configurable permission categories (revealCards, gameFlow,
issueManagement, roomSettings), each supporting three levels (everyone,
facilitators, owner).

- Schema: add ownerId/permissions to rooms, role to roomMemberships
- Backend: permission enforcement on all mutations, role management API
- Frontend: usePermissions hook, role badges, permission-gated UI
- Owner lockdown when owner leaves (explicit leave only)
- All new fields optional for full backward compatibility

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address PR review feedback for room permissions

- Remove duplicate transfer-ownership dialog from !isOpen branch
- Fix canRemoveTarget fallback to return false (prevent flash of enabled controls)
- Remove race-prone user creation fallback in rooms.create, use requireAuthUser
- Add authoritative room.ownerId check in transferOwnership
- Eliminate double room fetch by returning room from requireRoomPermission
- Replace getEffectivePermissions({} as never) with DEFAULT_PERMISSIONS
- Replace raw <select> with shadcn/ui Select for permissions dropdowns
- Fix Select closing settings panel by tracking open state via ref
- Improve permissions UI: add info tooltips, row descriptions, hover states
- Simplify tooltip ternary in issue-item.tsx

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: transfer room ownership during anonymous-to-permanent account linking

When a guest user creates a room then signs into a permanent account,
the merge path in linkAnonymousToPermanent deletes the old anonymous
user but left room.ownerId pointing to the deleted record. This caused
a false "owner has left" lockdown banner.

Now transfers room.ownerId to the permanent user before deleting the
anonymous record. Also short-circuits isRoomOwnerAbsent call in
getRoomWithRelatedData when no ownerId is set to reduce read
amplification on every subscription update.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: INQTR

convex/_generated/api.d.ts

@@ -26,11 +26,15 @@ import type * as model_canvas from "../model/canvas.js";
 import type * as model_cleanup from "../model/cleanup.js";
 import type * as model_demo from "../model/demo.js";
 import type * as model_issues from "../model/issues.js";
+import type * as model_permissions from "../model/permissions.js";
+import type * as model_roles from "../model/roles.js";
 import type * as model_rooms from "../model/rooms.js";
 import type * as model_timer from "../model/timer.js";
 import type * as model_users from "../model/users.js";
 import type * as model_votes from "../model/votes.js";
+import type * as permissions from "../permissions.js";
 import type * as presence from "../presence.js";
+import type * as roles from "../roles.js";
 import type * as rooms from "../rooms.js";
 import type * as scales from "../scales.js";
 import type * as timer from "../timer.js";
@@ -62,11 +66,15 @@ declare const fullApi: ApiFromModules<{
   "model/cleanup": typeof model_cleanup;
   "model/demo": typeof model_demo;
   "model/issues": typeof model_issues;
+  "model/permissions": typeof model_permissions;
+  "model/roles": typeof model_roles;
   "model/rooms": typeof model_rooms;
   "model/timer": typeof model_timer;
   "model/users": typeof model_users;
   "model/votes": typeof model_votes;
+  permissions: typeof permissions;
   presence: typeof presence;
+  roles: typeof roles;
   rooms: typeof rooms;
   scales: typeof scales;
   timer: typeof timer;

convex/issues.ts

@@ -1,7 +1,7 @@
 import { v } from "convex/values";
 import { query, mutation } from "./_generated/server";
 import * as Issues from "./model/issues";
-import { requireRoomMember } from "./model/auth";
+import { requireRoomPermission } from "./model/auth";
 
 /**
  * List all issues for a room, ordered by their order field
@@ -42,7 +42,7 @@ export const create = mutation({
     title: v.string(),
   },
   handler: async (ctx, args) => {
-    await requireRoomMember(ctx, args.roomId);
+    await requireRoomPermission(ctx, args.roomId, "issueManagement");
     return await Issues.createIssue(ctx, args);
   },
 });
@@ -58,7 +58,7 @@ export const updateTitle = mutation({
   handler: async (ctx, args) => {
     const issue = await ctx.db.get(args.issueId);
     if (!issue) throw new Error("Issue not found");
-    await requireRoomMember(ctx, issue.roomId);
+    await requireRoomPermission(ctx, issue.roomId, "issueManagement");
     await Issues.updateIssueTitle(ctx, args);
   },
 });
@@ -74,7 +74,7 @@ export const updateEstimate = mutation({
   handler: async (ctx, args) => {
     const issue = await ctx.db.get(args.issueId);
     if (!issue) throw new Error("Issue not found");
-    await requireRoomMember(ctx, issue.roomId);
+    await requireRoomPermission(ctx, issue.roomId, "issueManagement");
     await Issues.updateIssueEstimate(ctx, args);
   },
 });
@@ -87,7 +87,7 @@ export const remove = mutation({
   handler: async (ctx, args) => {
     const issue = await ctx.db.get(args.issueId);
     if (!issue) throw new Error("Issue not found");
-    await requireRoomMember(ctx, issue.roomId);
+    await requireRoomPermission(ctx, issue.roomId, "issueManagement");
     await Issues.removeIssue(ctx, args.issueId);
   },
 });
@@ -101,7 +101,7 @@ export const startVoting = mutation({
     issueId: v.id("issues"),
   },
   handler: async (ctx, args) => {
-    await requireRoomMember(ctx, args.roomId);
+    await requireRoomPermission(ctx, args.roomId, "gameFlow");
     await Issues.startVotingOnIssue(ctx, args);
   },
 });
@@ -115,7 +115,7 @@ export const reorder = mutation({
     issueIds: v.array(v.id("issues")),
   },
   handler: async (ctx, args) => {
-    await requireRoomMember(ctx, args.roomId);
+    await requireRoomPermission(ctx, args.roomId, "issueManagement");
     await Issues.reorderIssues(ctx, args);
   },
 });
@@ -126,7 +126,7 @@ export const reorder = mutation({
 export const clearCurrentIssue = mutation({
   args: { roomId: v.id("rooms") },
   handler: async (ctx, args) => {
-    await requireRoomMember(ctx, args.roomId);
+    await requireRoomPermission(ctx, args.roomId, "gameFlow");
     await Issues.clearCurrentIssue(ctx, args.roomId);
   },
 });

convex/model/auth.ts

@@ -1,5 +1,7 @@
 import { QueryCtx, MutationCtx } from "../_generated/server";
 import { Id, Doc } from "../_generated/dataModel";
+import { PermissionCategory } from "../permissions";
+import { requirePermission } from "./permissions";
 
 /**
  * Auth identity returned by ctx.auth.getUserIdentity().
@@ -81,3 +83,26 @@ export async function requireRoomMember(
   }
   return { identity, user, membership };
 }
+
+/**
+ * Requires authentication, room membership, AND permission for a specific category.
+ * Combines requireRoomMember + requirePermission in one call.
+ */
+export async function requireRoomPermission(
+  ctx: QueryCtx | MutationCtx,
+  roomId: Id<"rooms">,
+  category: PermissionCategory
+): Promise<{
+  identity: AuthIdentity;
+  user: Doc<"users">;
+  membership: Doc<"roomMemberships">;
+  room: Doc<"rooms">;
+}> {
+  const { identity, user, membership } = await requireRoomMember(ctx, roomId);
+  const room = await ctx.db.get(roomId);
+  if (!room) {
+    throw new Error("Room not found");
+  }
+  await requirePermission(ctx, room, membership, category);
+  return { identity, user, membership, room };
+}

convex/model/permissions.ts

@@ -0,0 +1,128 @@
+import { QueryCtx } from "../_generated/server";
+import { Doc } from "../_generated/dataModel";
+import {
+  MemberRole,
+  PermissionLevel,
+  PermissionCategory,
+  getEffectivePermissions,
+  getEffectiveRole,
+} from "../permissions";
+
+/**
+ * Checks whether a role satisfies a required permission level.
+ * - "everyone" → any role passes
+ * - "facilitators" → facilitator or owner passes
+ * - "owner" → only owner passes
+ */
+export function roleSatisfiesLevel(
+  role: MemberRole,
+  level: PermissionLevel
+): boolean {
+  if (level === "everyone") return true;
+  if (level === "facilitators") return role === "facilitator" || role === "owner";
+  if (level === "owner") return role === "owner";
+  return false;
+}
+
+/**
+ * Checks if the room owner has left (no active membership).
+ * Only explicit leave removes membership — network disconnect does NOT trigger this.
+ * Returns false for legacy rooms without an owner.
+ */
+export async function isRoomOwnerAbsent(
+  ctx: QueryCtx,
+  room: Doc<"rooms">
+): Promise<boolean> {
+  if (!room.ownerId) return false; // Legacy room, no owner set
+
+  const ownerMembership = await ctx.db
+    .query("roomMemberships")
+    .withIndex("by_room_user", (q) =>
+      q.eq("roomId", room._id).eq("userId", room.ownerId!)
+    )
+    .first();
+
+  return !ownerMembership;
+}
+
+/**
+ * Permission guard for mutations. Throws if the actor's role doesn't satisfy
+ * the required permission level for the given category.
+ *
+ * Lockdown logic: if the room owner is absent AND the category's permission
+ * level is "owner", throws an error. Facilitator-level and everyone-level
+ * actions are unaffected by lockdown.
+ */
+export async function requirePermission(
+  ctx: QueryCtx,
+  room: Doc<"rooms">,
+  membership: Doc<"roomMemberships">,
+  category: PermissionCategory
+): Promise<void> {
+  const permissions = getEffectivePermissions(room);
+  const level = permissions[category];
+  const role = getEffectiveRole(membership);
+
+  // Check lockdown: if owner is absent and this action requires owner level
+  if (level === "owner") {
+    const ownerAbsent = await isRoomOwnerAbsent(ctx, room);
+    if (ownerAbsent) {
+      throw new Error(
+        "Room owner has left. Owner-level actions are disabled until the owner returns."
+      );
+    }
+  }
+
+  if (!roleSatisfiesLevel(role, level)) {
+    throw new Error(
+      `Permission denied: ${category} requires "${level}" level`
+    );
+  }
+}
+
+/**
+ * Check if an actor can remove a target member.
+ * - Owner can remove anyone
+ * - Facilitator can remove participants only (not other facilitators or owner)
+ * - Participant cannot remove anyone
+ */
+export function canRemoveMember(
+  actorRole: MemberRole,
+  targetRole: MemberRole
+): boolean {
+  if (actorRole === "owner") return true;
+  if (actorRole === "facilitator") return targetRole === "participant";
+  return false;
+}
+
+/**
+ * Check if an actor can promote a target to facilitator.
+ * Owner and facilitator can promote participants.
+ */
+export function canPromoteToFacilitator(actorRole: MemberRole): boolean {
+  return actorRole === "owner" || actorRole === "facilitator";
+}
+
+/**
+ * Check if an actor can demote a facilitator to participant.
+ * Only owner can demote.
+ */
+export function canDemoteFacilitator(actorRole: MemberRole): boolean {
+  return actorRole === "owner";
+}
+
+/**
+ * Check if an actor can transfer ownership.
+ * Only owner can transfer.
+ */
+export function canTransferOwnership(actorRole: MemberRole): boolean {
+  return actorRole === "owner";
+}
+
+/**
+ * Check if an actor can change room permissions.
+ * Only owner can change permissions.
+ */
+export function canChangePermissions(actorRole: MemberRole): boolean {
+  return actorRole === "owner";
+}