refactor(auth): consolidate session-policy clamp semantics, shared security-policy version module, canonical bounds, docs

Author: waleedlatif1

apps/docs/content/docs/en/platform/enterprise/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "index",
     "sso",
+    "session-policies",
     "access-control",
     "custom-blocks",
     "whitelabeling",

apps/docs/content/docs/en/platform/enterprise/session-policies.mdx

@@ -0,0 +1,76 @@
+---
+title: Session Policies
+description: Set session lifetime limits and sign out every member of your organization at once
+---
+
+import { FAQ } from '@/components/ui/faq'
+
+Session Policies let organization owners and admins on Enterprise plans control how long member sign-in sessions last, and sign out every member org-wide in one action. Policies apply to every member of the organization on every device.
+
+---
+
+## Setup
+
+Go to **Settings → Security → Session policies** in your organization settings.
+
+Both limits are optional. Leave a field empty to keep the default behavior: sessions last 30 days and extend automatically while a member stays active.
+
+---
+
+## Settings
+
+### Max session lifetime
+
+Caps how long a session can exist from the moment a member signs in, regardless of activity. When the limit is reached, the member must sign in again.
+
+Use this to enforce periodic re-authentication — for example, a value of `168` requires everyone to sign in again at least weekly. Accepts 1 to 8760 hours (1 year).
+
+### Idle timeout
+
+Signs a member out after this many hours without activity. Activity extends the session, so members who use Sim regularly stay signed in; dormant sessions expire.
+
+Accepts 24 to 8760 hours. The 24-hour minimum exists because session activity is recorded at most once per day — a shorter window would sign out members who are actively working.
+
+### Sign out all members
+
+The **Sign out all members** action immediately revokes every member session in the organization except your own. Members are signed out on their next request — typically within a minute — and must sign in again.
+
+Use this after a security incident, an offboarding wave, or before tightening a policy you want to take effect everywhere at once.
+
+---
+
+## How enforcement works
+
+- **New sign-ins** get an expiry that respects the policy from the moment the session is created.
+- **Existing sessions** are shortened immediately when you save a tighter policy — no member keeps a longer session than the new policy allows.
+- **Loosening a policy never extends existing sessions.** Members pick up the longer limit the next time they sign in.
+- Changes propagate to active members within about a minute; there is no need to redeploy or wait for sessions to naturally expire.
+
+---
+
+## FAQ
+
+<FAQ
+  items={[
+    {
+      question: 'Do session policies apply to SSO sign-ins?',
+      answer:
+        'Yes. Sessions created through SSO follow the same lifetime and idle limits as any other sign-in method. Your identity provider may enforce its own, stricter session rules on top.',
+    },
+    {
+      question: 'What happens to a member who is working when their session expires?',
+      answer:
+        'They are redirected to sign in again on their next request. Unsaved workflow changes in the editor are preserved by the collaborative canvas, which continuously syncs edits.',
+    },
+    {
+      question: 'Does "Sign out all members" affect API keys or running workflows?',
+      answer:
+        'No. It revokes browser sign-in sessions only. API keys, deployed workflows, webhooks, and schedules keep working — manage those separately from the API keys settings.',
+    },
+    {
+      question: 'Why is the minimum idle timeout 24 hours?',
+      answer:
+        'Session activity is recorded at most once per 24 hours for performance. An idle timeout below that window could sign out members who are actively using Sim, so shorter values are not accepted.',
+    },
+  ]}
+/>

apps/sim/app/api/organizations/[id]/session-policy/route.test.ts

@@ -1,79 +1,36 @@
 /**
  * @vitest-environment node
  */
-import { createMockRequest } from '@sim/testing'
+import { member, organization } from '@sim/db/schema'
+import {
+  createMockRequest,
+  dbChainMock,
+  dbChainMockFns,
+  queueTableRows,
+  resetDbChainMock,
+} from '@sim/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-const {
-  mockDbState,
-  mockGetSession,
-  mockIsEnterprise,
-  mockBumpVersion,
-  mockRecordAudit,
-  mockExecute,
-  mockUpdateReturning,
-} = vi.hoisted(() => ({
-  mockDbState: { selectResults: [] as unknown[][] },
+const { mockGetSession, mockIsEnterprise, mockEagerClamp, mockRecordAudit } = vi.hoisted(() => ({
   mockGetSession: vi.fn(),
   mockIsEnterprise: vi.fn(),
-  mockBumpVersion: vi.fn(),
+  mockEagerClamp: vi.fn(),
   mockRecordAudit: vi.fn(),
-  mockExecute: vi.fn(),
-  mockUpdateReturning: vi.fn(),
 }))
 
-function createSelectChain() {
-  const chain = {
-    from: vi.fn(),
-    where: vi.fn(),
-    limit: vi.fn(),
-  }
-  chain.from.mockReturnValue(chain)
-  chain.where.mockReturnValue(chain)
-  chain.limit.mockImplementation(() => Promise.resolve(mockDbState.selectResults.shift() ?? []))
-  return chain
-}
-
-function createUpdateChain() {
-  const chain = {
-    set: vi.fn(),
-    where: vi.fn(),
-    returning: vi.fn(),
-  }
-  chain.set.mockReturnValue(chain)
-  chain.where.mockReturnValue(chain)
-  chain.returning.mockImplementation(() => Promise.resolve(mockUpdateReturning()))
-  return chain
-}
-
-vi.mock('@sim/db', () => ({
-  db: {
-    select: vi.fn(() => createSelectChain()),
-    update: vi.fn(() => createUpdateChain()),
-    execute: mockExecute,
-  },
-}))
-
-vi.mock('@sim/db/schema', () => ({
-  member: {
-    id: 'member.id',
-    organizationId: 'member.organizationId',
-    userId: 'member.userId',
-    role: 'member.role',
-  },
-  organization: {
-    id: 'organization.id',
-    name: 'organization.name',
-    sessionPolicySettings: 'organization.sessionPolicySettings',
-  },
-}))
+vi.mock('@sim/db', () => dbChainMock)
 
 vi.mock('@/lib/auth', () => ({
   getSession: mockGetSession,
 }))
 
 vi.mock('@/lib/auth/session-policy', () => ({
-  bumpSecurityPolicyVersion: mockBumpVersion,
+  eagerClampOrgSessions: mockEagerClamp,
+  invalidateSessionPolicyCache: vi.fn(),
+}))
+
+vi.mock('@/lib/auth/security-policy', () => ({
+  invalidateSecurityPolicyVersionCache: vi.fn(),
 }))
 
 vi.mock('@/lib/billing/core/subscription', () => ({
@@ -100,13 +57,12 @@ const routeContext = { params: Promise.resolve({ id: ORG_ID }) }
 describe('session policy route', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    mockDbState.selectResults = []
+    resetDbChainMock()
     mockGetSession.mockResolvedValue({
       user: { id: 'user-1', name: 'Admin', email: 'admin@acme.dev' },
       session: { token: 'tok-1' },
     })
     mockIsEnterprise.mockResolvedValue(true)
-    mockExecute.mockResolvedValue(undefined)
   })
 
   describe('GET', () => {
@@ -117,16 +73,16 @@ describe('session policy route', () => {
     })
 
     it('returns 403 for non-members', async () => {
-      mockDbState.selectResults = [[]]
+      queueTableRows(member, [])
       const response = await GET(createMockRequest('GET'), routeContext)
       expect(response.status).toBe(403)
     })
 
     it('returns the configured policy for members', async () => {
-      mockDbState.selectResults = [
-        [{ id: 'member-1' }],
-        [{ sessionPolicySettings: { maxSessionHours: 72, idleTimeoutHours: null } }],
-      ]
+      queueTableRows(member, [{ id: 'member-1' }])
+      queueTableRows(organization, [
+        { sessionPolicySettings: { maxSessionHours: 72, idleTimeoutHours: null } },
+      ])
       const response = await GET(createMockRequest('GET'), routeContext)
       expect(response.status).toBe(200)
       const body = await response.json()
@@ -143,32 +99,37 @@ describe('session policy route', () => {
     }
 
     it('rejects non-admin members', async () => {
-      mockDbState.selectResults = [[{ role: 'member' }]]
-      const response = await PUT(putRequest({ maxSessionHours: 72 }), routeContext)
+      queueTableRows(member, [{ role: 'member' }])
+      const response = await PUT(
+        putRequest({ maxSessionHours: 72, idleTimeoutHours: null }),
+        routeContext
+      )
       expect(response.status).toBe(403)
     })
 
     it('rejects an idle timeout below the cookie-cache window', async () => {
-      mockDbState.selectResults = [[{ role: 'admin' }]]
-      const response = await PUT(putRequest({ idleTimeoutHours: 5 }), routeContext)
+      queueTableRows(member, [{ role: 'admin' }])
+      const response = await PUT(
+        putRequest({ maxSessionHours: null, idleTimeoutHours: 5 }),
+        routeContext
+      )
       expect(response.status).toBe(400)
     })
 
     it('rejects non-enterprise organizations', async () => {
-      mockDbState.selectResults = [[{ role: 'owner' }]]
+      queueTableRows(member, [{ role: 'owner' }])
       mockIsEnterprise.mockResolvedValue(false)
-      const response = await PUT(putRequest({ maxSessionHours: 72 }), routeContext)
+      const response = await PUT(
+        putRequest({ maxSessionHours: 72, idleTimeoutHours: null }),
+        routeContext
+      )
       expect(response.status).toBe(403)
     })
 
     it('saves the policy, eagerly clamps sessions, and bumps the version', async () => {
-      mockDbState.selectResults = [
-        [{ role: 'owner' }],
-        [{ name: 'Acme', sessionPolicySettings: null }],
-      ]
-      mockUpdateReturning.mockReturnValue([
-        { sessionPolicySettings: { maxSessionHours: 72, idleTimeoutHours: 48 } },
-      ])
+      queueTableRows(member, [{ role: 'owner' }])
+      queueTableRows(organization, [{ name: 'Acme' }])
+      dbChainMockFns.returning.mockResolvedValueOnce([{ id: ORG_ID }])
 
       const response = await PUT(
         putRequest({ maxSessionHours: 72, idleTimeoutHours: 48 }),
@@ -177,29 +138,33 @@ describe('session policy route', () => {
       expect(response.status).toBe(200)
       const body = await response.json()
       expect(body.data.configured).toEqual({ maxSessionHours: 72, idleTimeoutHours: 48 })
-      expect(mockExecute).toHaveBeenCalledTimes(1)
-      expect(mockBumpVersion).toHaveBeenCalledWith(ORG_ID)
+      expect(mockEagerClamp).toHaveBeenCalledWith(ORG_ID, {
+        maxSessionHours: 72,
+        idleTimeoutHours: 48,
+      })
+      // The version bump rides the settings UPDATE (single round trip).
+      expect(dbChainMockFns.set).toHaveBeenCalledWith(
+        expect.objectContaining({ securityPolicyVersion: expect.anything() })
+      )
       expect(mockRecordAudit).toHaveBeenCalledWith(
         expect.objectContaining({ action: 'organization.session_policy.updated' })
       )
     })
 
-    it('skips the eager clamp when both policy fields are cleared', async () => {
-      mockDbState.selectResults = [
-        [{ role: 'owner' }],
-        [{ name: 'Acme', sessionPolicySettings: { maxSessionHours: 72 } }],
-      ]
-      mockUpdateReturning.mockReturnValue([
-        { sessionPolicySettings: { maxSessionHours: null, idleTimeoutHours: null } },
-      ])
+    it('clearing both fields still saves and delegates the no-op to the clamp', async () => {
+      queueTableRows(member, [{ role: 'owner' }])
+      queueTableRows(organization, [{ name: 'Acme' }])
+      dbChainMockFns.returning.mockResolvedValueOnce([{ id: ORG_ID }])
 
       const response = await PUT(
         putRequest({ maxSessionHours: null, idleTimeoutHours: null }),
         routeContext
       )
       expect(response.status).toBe(200)
-      expect(mockExecute).not.toHaveBeenCalled()
-      expect(mockBumpVersion).toHaveBeenCalledWith(ORG_ID)
+      expect(mockEagerClamp).toHaveBeenCalledWith(ORG_ID, {
+        maxSessionHours: null,
+        idleTimeoutHours: null,
+      })
     })
   })
 })