fix(workspaces): address review comments across stacked PRs

backend/src/auth/auth.ts

@@ -212,8 +212,10 @@ export const createAuth = (database: typeof DbType, emailDeps: AuthEmailDeps = {
           }),
           // Promote any pending memberships invited by email. The personal workspace
           // itself is FE-created (uploaded via PowerSync with a deterministic id), so
-          // this hook only handles the admin-only pending-membership flow that the FE
-          // can't see. Skipped for anonymous users — anon never receives invites.
+          // this hook only handles the cross-workspace promotion flow — a brand-new
+          // user isn't a member of anything yet, so no FE client can see (let alone
+          // act on) the invite at signup time. Skipped for anonymous users — anon
+          // never receives invites.
           after: async (createdUser) => {
             const isAnonymous = (createdUser as { isAnonymous?: boolean }).isAnonymous === true
             if (isAnonymous) {

backend/src/config/settings.test.ts

@@ -51,6 +51,33 @@ describe('Config Settings', () => {
     })
   })
 
+  describe('SERVER_ID validation', () => {
+    const savedServerId = process.env.SERVER_ID
+
+    afterEach(() => {
+      if (savedServerId !== undefined) {
+        process.env.SERVER_ID = savedServerId
+      } else {
+        delete process.env.SERVER_ID
+      }
+      clearSettingsCache()
+    })
+
+    it('surfaces a setup-pointing error when SERVER_ID is unset', () => {
+      delete process.env.SERVER_ID
+      clearSettingsCache()
+
+      expect(() => getSettings()).toThrow(/SERVER_ID env var must be set.*make doctor/)
+    })
+
+    it('surfaces a UUID-format error when SERVER_ID is set but not a UUID', () => {
+      process.env.SERVER_ID = 'not-a-uuid'
+      clearSettingsCache()
+
+      expect(() => getSettings()).toThrow(/SERVER_ID must be a valid UUID/)
+    })
+  })
+
   describe('CORS default security', () => {
     const corsEnvKeys = ['CORS_ORIGINS'] as const
 

backend/src/config/settings.ts

@@ -13,7 +13,15 @@ const settingsSchema = z
     // key the trust-domain registry (auth token, device ID, encryption keys, DB filename
     // are all namespaced by this). No default — TS-enforced to prevent ID duplication
     // across deployments. `make doctor` auto-generates one for local dev.
-    serverId: z.string().uuid(),
+    //
+    // Custom messages mirror the BETTER_AUTH_SECRET ergonomics: a raw `Expected
+    // string, received undefined` ZodError doesn't tell a fresh dev what to do.
+    serverId: z
+      .string({
+        error:
+          'SERVER_ID env var must be set to a stable per-deployment UUID. Run `make doctor` to auto-generate one for local dev.',
+      })
+      .uuid({ error: 'SERVER_ID must be a valid UUID.' }),
 
     // API Keys
     fireworksApiKey: z.string().default(''),

backend/src/dal/workspaces.ts

@@ -20,8 +20,9 @@ import { v7 as uuidv7 } from 'uuid'
  * Called from the Better Auth post-user-create hook. The personal workspace
  * itself is FE-created (uploaded via PowerSync with a deterministic id from
  * `shared/workspaces.ts`) — the BE no longer creates one here. Pending
- * promotion stays server-side because pending rows live in an admin-only
- * sync bucket and FE can't see other users' invites until they're memberships.
+ * promotion stays server-side because a brand-new user isn't a member of any
+ * workspace yet, so no FE client can see (or act on) the pending invite at
+ * signup time.
  *
  * Skipped for anonymous users — anon never receives pending invites.
  */
@@ -251,6 +252,30 @@ export const getMembershipById = async (
   return rows[0] ?? null
 }
 
+/**
+ * Look up a membership by `(workspace_id, user_id)` — the unique constraint
+ * that `upsertMembership` collides on. Upload-handler validation uses this to
+ * detect when a PUT would effectively change an existing role (treated as a
+ * PATCH for auth purposes).
+ */
+export const getMembershipByWorkspaceAndUser = async (
+  database: typeof DbType,
+  workspaceId: string,
+  userId: string,
+): Promise<MembershipRow | null> => {
+  const rows = await database
+    .select({
+      id: workspaceMembershipsTable.id,
+      workspaceId: workspaceMembershipsTable.workspaceId,
+      userId: workspaceMembershipsTable.userId,
+      role: workspaceMembershipsTable.role,
+    })
+    .from(workspaceMembershipsTable)
+    .where(and(eq(workspaceMembershipsTable.workspaceId, workspaceId), eq(workspaceMembershipsTable.userId, userId)))
+    .limit(1)
+  return rows[0] ?? null
+}
+
 export const getPendingMembershipById = async (database: typeof DbType, id: string): Promise<PendingRow | null> => {
   const rows = await database
     .select({
@@ -409,6 +434,23 @@ export const upsertMembership = async (database: typeof DbType, input: Membershi
     })
 }
 
+/**
+ * Insert a membership row only if no row with the same `(workspace_id, user_id)`
+ * already exists. Used by the promote-on-insert path in the pending-membership
+ * upload handler: an invite for an email that already belongs to a member must
+ * not overwrite that member's existing role (otherwise an invite for an admin's
+ * own email would downgrade them to whatever role the invite carried). Mirrors
+ * the `promotePendingMemberships` DO-NOTHING semantics for the signup path.
+ */
+export const insertMembershipIfMissing = async (database: typeof DbType, input: MembershipInput): Promise<void> => {
+  await database
+    .insert(workspaceMembershipsTable)
+    .values(input)
+    .onConflictDoNothing({
+      target: [workspaceMembershipsTable.workspaceId, workspaceMembershipsTable.userId],
+    })
+}
+
 /**
  * Mirrors a user's current display info onto every one of their membership rows.
  * Called from the Better Auth `update.after` hook so name/email changes propagate
@@ -510,6 +552,32 @@ export const deletePendingMembership = async (database: typeof DbType, id: strin
   return rows.length
 }
 
+/**
+ * Deletes the pending row for `(workspace_id, email)`. Used by the
+ * promote-on-insert path in the upload handler: when `upsertPendingMembership`
+ * conflicts on the `(workspace_id, email)` unique constraint, Postgres keeps
+ * the existing row's id, so a delete keyed on the upload's `op.id` would no-op
+ * and leave a stale pending invite behind for someone who is now a real
+ * member. Email is normalized to match `upsertPendingMembership`'s storage.
+ */
+export const deletePendingMembershipByWorkspaceAndEmail = async (
+  database: typeof DbType,
+  workspaceId: string,
+  email: string,
+): Promise<number> => {
+  const normalizedEmail = normalizeEmail(email)
+  const rows = await database
+    .delete(workspacePendingMembershipsTable)
+    .where(
+      and(
+        eq(workspacePendingMembershipsTable.workspaceId, workspaceId),
+        eq(workspacePendingMembershipsTable.email, normalizedEmail),
+      ),
+    )
+    .returning()
+  return rows.length
+}
+
 export type WorkspacePermissionInput = {
   id: string
   workspaceId: string

backend/src/lib/email.ts

@@ -8,3 +8,13 @@
  * - Trims whitespace
  */
 export const normalizeEmail = (email: string) => email.toLowerCase().trim()
+
+/**
+ * Format check (same regex as the FE's `isValidEmailFormat`) — guards
+ * upload-handler inserts against junk strings before they hit the DB. Run
+ * against the normalized form so case/whitespace don't sneak past.
+ */
+const emailRegex =
+  /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/
+
+export const isValidEmailFormat = (email: string): boolean => emailRegex.test(normalizeEmail(email))

backend/src/powersync/upload-handlers/helpers.ts

@@ -2,7 +2,9 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-import type { HandlerResult } from './types'
+import { getRequiredRoleForPermission, getUserRoleInWorkspace } from '@/dal/workspaces'
+import { permissionAllows, type WorkspacePermissionKey } from '@shared/workspaces'
+import type { HandlerResult, UploadTx } from './types'
 
 /** Column names Drizzle declares as `timestamp(...)`; JSON sends them as ISO strings. */
 const timestampDbColumns = new Set(['deleted_at', 'last_seen', 'created_at', 'revoked_at', 'updated_at'])
@@ -42,3 +44,22 @@ export const reject = (rejectionClass: 'permanent' | 'transient', code: string):
   class: rejectionClass,
   code,
 })
+
+/**
+ * Resolves the caller's role + the configured permission's required role and
+ * returns whether the op is allowed. Defaults `required_role` to `'admin'`
+ * when no `workspace_permissions` row exists for the key (Decision 11) so an
+ * unconfigured workspace stays admin-only. Shared by every handler that gates
+ * writes on `workspace_permissions` — keep the lookup in one place so the
+ * default-to-admin policy can't drift between tables.
+ */
+export const callerSatisfiesPermission = async (
+  tx: UploadTx,
+  workspaceId: string,
+  userId: string,
+  permissionKey: WorkspacePermissionKey,
+): Promise<boolean> => {
+  const required = (await getRequiredRoleForPermission(tx, workspaceId, permissionKey)) ?? 'admin'
+  const userRole = await getUserRoleInWorkspace(tx, workspaceId, userId)
+  return permissionAllows(userRole, required)
+}