refactor(scim): one removal invariant, honest provenance, finished primitive extraction, tests

Findings from an independent three-way audit (architecture, correctness,
tests) after the review rounds:

- Removing a member is one transaction that also revokes sessions and
  personal keys and retires the directory row into its tombstone, so a
  member can never be gone while the directory says otherwise. The four
  defensive re-checks the review rounds had added are gone; deprovision is
  one path and the settings UI removal gains the same revocation
- Every satisfied mapping is recorded; access the person already held is
  recorded as `adopted` and left alone on withdrawal unless the directory is
  the source of truth. Reconcile is idempotent again
- Permission-group conflict rules live once, in the shared membership
  primitive; the settings routes and the workspace-member route use the
  shared primitives; direct workspace grants honor managed-membership lock
- Lock order: the permission-group leaf lock precedes every write to its
  row; deadlocks map to 503 like lock timeouts; credential issue serializes
  on the organization lock; reconcile batches shrink to 25
- PATCH keeps unmodelled attributes under `extra` as create and replace do,
  so Entra's default mappings no longer fail whole updates
- Unknown group members are dropped with a warning; Entra's legacy User
  schema marker is tolerated; the directory re-asserts an account address
  that drifted; relink lifts a lingering suspension; a reconcile pass
  advances the watermark only when it completes and re-reads settings per
  batch; instance-organization deployments refuse a connection for any
  other organization; provisioning cleans up through account deletion
- Base URL, credential predicate, request-log type, audit recording, and
  seat policy each live in one place; `ssoProviderId` and the unused
  credential scope parameter are removed
- Tests for the reconciler, user updates, deprovision, the route builder,
  entitlement, auto-map, and the shared conflict rules; docs corrected

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DGXcwsHzYGp6pUDWRtJKpz

Author: waleedlatif1

apps/docs/content/docs/platform/enterprise/scim.mdx

@@ -24,7 +24,7 @@ It pairs with [SSO](/platform/enterprise/sso). SSO proves who someone is when th
 | Updates their name or email | Updates the Sim account, and ends their sessions if the address changed |
 | Deactivates them | Blocks sign-in and stops their personal API keys. Everything they own, and every grant they hold, is left untouched; shared workspace keys keep working |
 | Reactivates them | Restores access exactly as it was |
-| Removes them from the app | Removes their organization membership and reassigns what they owned |
+| Removes them from the app | Removes their organization membership, ends their sessions, deletes their personal API keys, and reassigns what they owned |
 | Adds them to a group | Grants whatever that group maps to |
 
 Deactivation is reversible and never destructive. Someone on leave keeps their workflows, their credentials, and their workspace history; they simply cannot sign in.
@@ -131,7 +131,7 @@ A group can carry several mappings. When two groups grant the same workspace at
 
 Sim records every grant it makes on your behalf. When someone leaves a group, only what the directory granted is taken back — access a workspace administrator granted by hand stays.
 
-The one exception is **managed membership locking**, which is on by default. With it on, the directory is the source of truth: Sim refuses invitations, role changes, and manual grants for provisioned members, because the next sync would revert them anyway. Turn it off if you want to layer manual access on top of directory access.
+The one exception is **managed membership locking**, which is on by default. With it on, the directory is the source of truth: Sim refuses invitations, workspace grants, and role changes for provisioned members, because the next sync would revert them anyway. Removals stay possible so an administrator can always act in an emergency. Turn it off if you want to layer manual access on top of directory access.
 
 ## Provisioning and SSO together
 
@@ -143,7 +143,7 @@ If you want the directory to be the only way in, enable **Disable just-in-time p
 
 **Settings → SSO → Directory provisioning → Activity** lists recent requests with their status and, for a failure, what was wrong. Providers report a failed cycle without saying what they sent, so this is usually the fastest way to see the cause.
 
-Sim also re-applies every group mapping on a schedule, so drift cannot persist. You can run it on demand with **Reconcile now**.
+Sim also re-applies every group mapping once an hour, so drift cannot persist. You can run it on demand with **Reconcile now**, which is also how a change to the connection settings reaches members before the next sync.
 
 ## Reference
 

apps/sim/app/api/cron/scim-reconcile/route.ts

@@ -2,7 +2,7 @@ import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
 import { type NextRequest, NextResponse } from 'next/server'
 import { verifyCronAuth } from '@/lib/auth/internal'
-import { isBillingEnabled, isScimEnabled } from '@/lib/core/config/env-flags'
+import { isScimEnabled } from '@/lib/core/config/env-flags'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { runScimReconcileSweep } from '@/lib/scim/reconcile/job'
 
@@ -16,7 +16,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
   const authError = verifyCronAuth(request, 'SCIM reconciliation')
   if (authError) return authError
 
-  if (!isBillingEnabled && !isScimEnabled) {
+  if (!isScimEnabled) {
     return NextResponse.json({ success: true, connections: 0, skipped: 'disabled' })
   }
 

apps/sim/app/api/organizations/[id]/permission-groups/[groupId]/members/bulk/route.ts

@@ -10,15 +10,17 @@ import { bulkAddPermissionGroupMembersContract } from '@/lib/api/contracts/permi
 import { getValidationErrorMessage, parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  findScopeConflicts,
+  type ScopeConflict,
+} from '@/lib/permission-groups/application/group-membership'
 import { PERMISSION_GROUP_MEMBER_CONSTRAINTS } from '@/lib/permission-groups/constraints'
 import { acquirePermissionGroupOrgLock } from '@/lib/permission-groups/locks'
 import {
   authorizeOrgAccessControl,
-  findScopeConflicts,
   formatScopeConflictError,
   getGroupWorkspaces,
   loadGroupInOrganization,
-  type ScopeConflict,
 } from '@/app/api/organizations/[id]/permission-groups/utils'
 
 const logger = createLogger('OrganizationPermissionGroupBulkMembers')

apps/sim/app/api/organizations/[id]/permission-groups/[groupId]/members/route.ts

@@ -10,19 +10,21 @@ import { addPermissionGroupMemberContract } from '@/lib/api/contracts/permission
 import { getValidationErrorMessage, parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  type AllMembersConflict,
+  findAllMembersWorkspaceConflict,
+  findScopeConflicts,
+  type ScopeConflict,
+} from '@/lib/permission-groups/application/group-membership'
 import { PERMISSION_GROUP_MEMBER_CONSTRAINTS } from '@/lib/permission-groups/constraints'
 import { acquirePermissionGroupOrgLock } from '@/lib/permission-groups/locks'
 import { isOrganizationMember } from '@/lib/workspaces/permissions/utils'
 import {
-  type AllMembersConflict,
   authorizeOrgAccessControl,
-  findAllMembersWorkspaceConflict,
-  findScopeConflicts,
   formatAllMembersConflictError,
   formatScopeConflictError,
   getGroupWorkspaces,
   loadGroupInOrganization,
-  type ScopeConflict,
 } from '@/app/api/organizations/[id]/permission-groups/utils'
 
 const logger = createLogger('OrganizationPermissionGroupMembers')

apps/sim/app/api/organizations/[id]/permission-groups/[groupId]/route.ts

@@ -10,23 +10,25 @@ import { updatePermissionGroupContract } from '@/lib/api/contracts/permission-gr
 import { getValidationErrorMessage, parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  type AllMembersConflict,
+  findAllMembersWorkspaceConflict,
+  findScopeConflicts,
+  type ScopeConflict,
+} from '@/lib/permission-groups/application/group-membership'
 import { PERMISSION_GROUP_CONSTRAINTS } from '@/lib/permission-groups/constraints'
 import {
   type PermissionGroupConfig,
   parsePermissionGroupConfig,
 } from '@/lib/permission-groups/fields'
 import { acquirePermissionGroupOrgLock } from '@/lib/permission-groups/locks'
 import {
-  type AllMembersConflict,
   authorizeOrgAccessControl,
-  findAllMembersWorkspaceConflict,
-  findScopeConflicts,
   findWorkspacesNotInOrganization,
   formatAllMembersConflictError,
   formatScopeConflictError,
   getGroupWorkspaces,
   loadGroupInOrganization,
-  type ScopeConflict,
 } from '@/app/api/organizations/[id]/permission-groups/utils'
 
 const logger = createLogger('OrganizationPermissionGroup')

apps/sim/app/api/organizations/[id]/permission-groups/route.ts

@@ -15,6 +15,10 @@ import { createPermissionGroupContract } from '@/lib/api/contracts/permission-gr
 import { getValidationErrorMessage, parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  type AllMembersConflict,
+  findAllMembersWorkspaceConflict,
+} from '@/lib/permission-groups/application/group-membership'
 import { PERMISSION_GROUP_CONSTRAINTS } from '@/lib/permission-groups/constraints'
 import {
   DEFAULT_PERMISSION_GROUP_CONFIG,
@@ -23,9 +27,7 @@ import {
 } from '@/lib/permission-groups/fields'
 import { acquirePermissionGroupOrgLock } from '@/lib/permission-groups/locks'
 import {
-  type AllMembersConflict,
   authorizeOrgAccessControl,
-  findAllMembersWorkspaceConflict,
   findWorkspacesNotInOrganization,
   formatAllMembersConflictError,
   getWorkspacesForGroups,

apps/sim/app/api/organizations/[id]/permission-groups/utils.test.ts

@@ -1,8 +1,7 @@
 /**
  * @vitest-environment node
  */
-import { permissionGroup, permissionGroupMember } from '@sim/db/schema'
-import { queueTableRows, resetDbChainMock } from '@sim/testing'
+import { resetDbChainMock } from '@sim/testing'
 import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
 
 const { mockIsOrganizationAdminOrOwner, mockIsOrganizationOnEnterprisePlan } = vi.hoisted(() => ({
@@ -18,11 +17,7 @@ vi.mock('@/lib/workspaces/permissions/utils', () => ({
   isOrganizationAdminOrOwner: mockIsOrganizationAdminOrOwner,
 }))
 
-import {
-  authorizeOrgAccessControl,
-  findAllMembersWorkspaceConflict,
-  findScopeConflicts,
-} from '@/app/api/organizations/[id]/permission-groups/utils'
+import { authorizeOrgAccessControl } from '@/app/api/organizations/[id]/permission-groups/utils'
 
 afterAll(resetDbChainMock)
 
@@ -66,111 +61,3 @@ describe('authorizeOrgAccessControl', () => {
     expect(response).toBeNull()
   })
 })
-
-describe('findScopeConflicts', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    resetDbChainMock()
-  })
-
-  const baseParams = {
-    organizationId: 'org-1',
-    excludeGroupId: 'group-1',
-    workspaceIds: ['ws-1'],
-    candidateUserIds: ['user-1'],
-  }
-
-  const conflictRow = (userId: string, otherGroupName = 'Marketing') => ({
-    userId,
-    userName: 'User One',
-    userEmail: `${userId}@example.com`,
-    otherGroupId: 'group-2',
-    otherGroupName,
-  })
-
-  it('returns no conflicts when there are no candidate users', async () => {
-    queueTableRows(permissionGroupMember, [conflictRow('user-1')])
-
-    const conflicts = await findScopeConflicts({ ...baseParams, candidateUserIds: [] })
-
-    expect(conflicts).toEqual([])
-  })
-
-  it('returns no conflicts when there are no target workspaces', async () => {
-    queueTableRows(permissionGroupMember, [conflictRow('user-1')])
-
-    const conflicts = await findScopeConflicts({ ...baseParams, workspaceIds: [] })
-
-    expect(conflicts).toEqual([])
-  })
-
-  it('flags a candidate already in another group that shares a workspace', async () => {
-    queueTableRows(permissionGroupMember, [conflictRow('user-1')])
-
-    const conflicts = await findScopeConflicts(baseParams)
-
-    expect(conflicts.map((c) => c.userId)).toEqual(['user-1'])
-    expect(conflicts[0].conflictingGroupName).toBe('Marketing')
-  })
-
-  it('returns at most one conflict per user', async () => {
-    queueTableRows(permissionGroupMember, [
-      conflictRow('user-1', 'Marketing'),
-      conflictRow('user-1', 'Sales'),
-    ])
-
-    const conflicts = await findScopeConflicts(baseParams)
-
-    expect(conflicts).toHaveLength(1)
-    expect(conflicts[0].conflictingGroupName).toBe('Marketing')
-  })
-
-  it('returns no conflicts when the query finds no overlapping memberships', async () => {
-    const conflicts = await findScopeConflicts(baseParams)
-
-    expect(conflicts).toEqual([])
-  })
-})
-
-describe('findAllMembersWorkspaceConflict', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    resetDbChainMock()
-  })
-
-  const baseParams = {
-    organizationId: 'org-1',
-    excludeGroupId: 'group-1',
-    workspaceIds: ['ws-1', 'ws-2'],
-  }
-
-  it('returns null when there are no target workspaces', async () => {
-    queueTableRows(permissionGroup, [
-      { conflictingGroupId: 'group-2', conflictingGroupName: 'Marketing', workspaceName: 'Acme' },
-    ])
-
-    const conflict = await findAllMembersWorkspaceConflict({ ...baseParams, workspaceIds: [] })
-
-    expect(conflict).toBeNull()
-  })
-
-  it('returns the conflicting all-members group sharing a workspace', async () => {
-    queueTableRows(permissionGroup, [
-      { conflictingGroupId: 'group-2', conflictingGroupName: 'Marketing', workspaceName: 'Acme' },
-    ])
-
-    const conflict = await findAllMembersWorkspaceConflict(baseParams)
-
-    expect(conflict).toEqual({
-      conflictingGroupId: 'group-2',
-      conflictingGroupName: 'Marketing',
-      workspaceName: 'Acme',
-    })
-  })
-
-  it('returns null when no other all-members group targets the workspaces', async () => {
-    const conflict = await findAllMembersWorkspaceConflict(baseParams)
-
-    expect(conflict).toBeNull()
-  })
-})