feat(billing): multi-user paywall: multi_user capability, 20-day grace, owner-only dormancy (#2099)

* feat(billing): multi-user seat gate: multi_user capability, 20-day grace, owner-only dormancy

Multiple people in one company becomes a paid capability (multi_user, the
eighth PAID key). Derived at access time from capability_grants, no status
column, no enforcement cron:

- entitled: active grant (trial/stripe/team/manual/comp), everyone works
- grace: newest grant expired < 20 days ago; countdown banner for everyone
  in companies with > 1 user; invites still allowed
- frozen: only role=owner resolves; other memberships go dormant (rows
  untouched, paying reactivates instantly); invites 403 with paid-plan upsell

Enforcement: new resolve_active_company_gated RPC (zero-arg RPC and RLS twin
untouched: they also run on self-hosts, where the gate never bites), gated
query fallback for service-role/API-key paths, setActiveCompany guard, MCP
company-access check, invite route. Middleware routes all-frozen users to a
new /paused page; the switcher greys locked companies.

Migration 20260901081417 (applied to staging): trial trigger seeds
multi_user, backfills for mid-trial companies, active Stripe subs, team
agreements, and a grandfather grant (expires now, i.e. grace = deploy + 20
days) for existing unpaid multi-member companies. Daily cron mails owners at
grace start and last day. Strings in sv+en; pg-real + unit tests included.

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

* fix(billing): multi-user seat gate hardening from skeptic review

- Stripe cancel now EXPIRES the multi_user stripe grant instead of deleting
  it: the 20-day grace window hangs on an expired row, so a deleted one
  froze churned payers' staff instantly with no banner and no mail. Other
  stripe grants keep the freeze-and-retain delete.
- New SECURITY DEFINER company_multi_user_state() RPC (migration
  20260901083726, applied to staging) and RPC-first getMultiUserState:
  capability_grants RLS hides team-scoped rows from non-team users, so
  user-client reads misread byra-covered companies as frozen (switch
  refusal, wrong switcher locks).
- Byra-kind teams get a standing team-scoped multi_user grant (backfill +
  teams trigger): byra client companies have no company-scoped trial by
  design, so a grantless byra team would freeze every consultant and
  client user.
- Comped/manual companies with active PAID-key grants extend to multi_user
  (a comped company must not read as paying while locking out user two).
- /api/v1 gets the same dormancy gate as MCP (frozen non-owner -> 403).
- PGRST202 on resolution fails OPEN (pre-migration DB has zero multi_user
  rows; the gated fallback would have frozen every non-owner mid-deploy).
- Grace cron: covers team-scoped lapses (byra agreement ending) and skips
  the start mail for the hand-mailed grandfather cohort.
- Tests updated/added across all touched surfaces; pg tests for the new
  RPC and byra trigger; trial-suppression pg test extended to 8 keys.

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

* fix(billing): decouple seat-gate env check and fail open on gate read throws

CI round 1 on #2099:
- isMultiUserEnforced no longer imports has-capability: several route test
  suites partially mock that module and the vitest mock guard threw from
  inside the v1 seat gate, turning expected 4xx responses into 500s.
  multi_user is never a connector capability, so the bypass reduces to the
  same env reads, now inlined.
- getMultiUserState wraps its resolution in a fail-open try/catch: a client
  without .rpc or a thrown network error must never lock users out.
- no-phantom-columns ceiling 391 -> 393 with reasons: the seat gate's .or()
  scope filter (server-resolved UUIDs) and the Stripe cancel expiry update's
  timestamp .or(); all columns in both strings are literals.

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

* fix(billing): membership-guard the multi-user entitlement RPCs (Superagent P3)

company_multi_user_ok and company_multi_user_state are SECURITY DEFINER and
were granted to authenticated with a caller-supplied company UUID: any
logged-in user could probe an arbitrary company's billing state and grace
deadline across tenants. Migration 20260901091752 (applied to staging)
requires an auth.uid() membership in the target company when a JWT is
present, keeps service-role/definer contexts unrestricted, and clamps the
grace window to [0, 20] days. pg tests: stranger gets false/NULL, member
reads normally, oversized p_grace_days cannot widen the probe.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

app/api/company/members/invite/__tests__/route.test.ts

@@ -29,6 +29,14 @@ vi.mock('@/lib/auth/require-write', () => ({
   requireWritePermission: (...args: unknown[]) => requireWriteMock(...args),
 }))
 
+// Multi-user seat gate: mocked so the queued table mock's enqueue order stays
+// untouched for the pre-existing tests; the gate's own behavior is covered in
+// lib/entitlements/__tests__/multi-user.test.ts.
+const getMultiUserStateMock = vi.hoisted(() => vi.fn())
+vi.mock('@/lib/entitlements/multi-user', () => ({
+  getMultiUserState: (...args: unknown[]) => getMultiUserStateMock(...args),
+}))
+
 vi.mock('@/lib/supabase/server', () => ({
   createServiceClient: () => serviceSupabase,
 }))
@@ -87,6 +95,7 @@ beforeEach(() => {
     error: null,
   })
   requireWriteMock.mockResolvedValue({ ok: true })
+  getMultiUserStateMock.mockResolvedValue({ state: 'entitled', graceEndsAt: null })
   isConfiguredMock.mockReturnValue(true)
   sendEmailMock.mockResolvedValue({ success: true, messageId: 'msg-1' })
   brandSenderMock.getSenderForCompany.mockResolvedValue({
@@ -133,6 +142,38 @@ describe('POST /api/company/members/invite', () => {
     expect(body.error).toBe('Behörighet saknas.')
   })
 
+  it('blocks invites with 403 + upsell when multi_user is frozen', async () => {
+    getMultiUserStateMock.mockResolvedValue({ state: 'frozen', graceEndsAt: null })
+    enqueue({ data: { role: 'owner' } }) // caller membership
+
+    const { status, body } = await parseJsonResponse<{
+      error: string
+      capability_blocked: boolean
+      capability: string
+    }>(await post({ email: 'x@y.se' }))
+
+    expect(status).toBe(403)
+    expect(body.error).toBe('Bjud in fler personer med betald plan.')
+    expect(body.capability_blocked).toBe(true)
+    expect(body.capability).toBe('multi_user')
+    expect(sendEmailMock).not.toHaveBeenCalled()
+  })
+
+  it('still allows invites during the post-lapse grace window', async () => {
+    getMultiUserStateMock.mockResolvedValue({
+      state: 'grace',
+      graceEndsAt: new Date(Date.now() + 5 * 86_400_000).toISOString(),
+    })
+    enqueue({ data: { role: 'owner' } }) // caller membership
+    enqueue({ data: [] }) // existing members
+    enqueue({ data: null }) // existing invite
+    enqueue({ data: { name: 'Acme AB' } }) // company name
+    enqueue({ data: null }) // insert invitation
+
+    const { status } = await parseJsonResponse(await post({ email: 'x@y.se' }))
+    expect(status).toBe(200)
+  })
+
   it('rejects an invalid email with 400', async () => {
     enqueue({ data: { role: 'owner' } })
     const { status } = await parseJsonResponse(await post({ email: 'not-an-email' }))

app/api/company/members/invite/route.ts

@@ -6,6 +6,8 @@ import { withRouteContext } from '@/lib/api/with-route-context'
 import { validateBody } from '@/lib/api/validate'
 import { generateInviteToken, getInviteExpiry } from '@/lib/auth/invite-tokens'
 import { getErrorMessage } from '@/lib/errors/get-error-message'
+import { CAPABILITY } from '@/lib/entitlements/keys'
+import { getMultiUserState } from '@/lib/entitlements/multi-user'
 import { getEmailService } from '@/lib/email/service'
 import { getSenderForCompany, getBaseUrlForBrand } from '@/lib/email/brand-sender'
 import {
@@ -70,6 +72,24 @@ export const POST = withRouteContext(
       return NextResponse.json({ error: 'Behörighet saknas.' }, { status: 403 })
     }
 
+    // Multi-user seat gate: inviting more people requires the multi_user
+    // capability (paid plan or trial). A company in its post-lapse grace
+    // window may still invite (its people were promised 20 undisturbed
+    // days); only the frozen state blocks. Same envelope shape as
+    // capabilityBlockedResponse so the UI upsells consistently.
+    const multiUserAccess = await getMultiUserState(serviceClient, companyId)
+    if (multiUserAccess.state === 'frozen') {
+      return NextResponse.json(
+        {
+          error: 'Bjud in fler personer med betald plan.',
+          error_en: 'Invite more people with a paid plan.',
+          capability_blocked: true,
+          capability: CAPABILITY.multi_user,
+        },
+        { status: 403 },
+      )
+    }
+
     const validation = await validateBody(request, InviteSchema, {
       log,
       operation: 'company_members.invite',

app/api/company/members/route.ts

@@ -1,6 +1,7 @@
 import { createServiceClient } from '@/lib/supabase/server'
 import { NextResponse } from 'next/server'
 import { withRouteContext } from '@/lib/api/with-route-context'
+import { getMultiUserState } from '@/lib/entitlements/multi-user'
 
 /**
  * GET /api/company/members
@@ -60,6 +61,13 @@ export const GET = withRouteContext('company_members.list', async (_request, ctx
   const currentMember = members?.find((m) => m.user_id === user.id)
   const canInvite = currentMember?.role === 'owner' || currentMember?.role === 'admin'
 
+  // Multi-user seat gate: when the company is frozen (no multi_user grant
+  // active or in grace), the invite POST answers 403, so the UI swaps the
+  // invite form for the paid-plan upsell instead of a dead form.
+  const multiUserAccess = canInvite
+    ? await getMultiUserState(serviceClient, companyId)
+    : null
+
   return NextResponse.json({
     data: {
       members: (members || []).map((m) => ({
@@ -73,6 +81,7 @@ export const GET = withRouteContext('company_members.list', async (_request, ctx
       })),
       invitations: invitations || [],
       canInvite,
+      inviteRequiresUpgrade: multiUserAccess?.state === 'frozen',
     },
   })
 })

app/api/notifications/multi-user-grace/cron/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from 'next/server'
+import { ensureInitialized } from '@/lib/init'
+import { withCronContext } from '@/lib/api/with-cron-context'
+import { createServiceClient } from '@/lib/supabase/server'
+import { runMultiUserGraceReminders } from '@/lib/notifications/multi-user-grace'
+
+ensureInitialized()
+
+/**
+ * GET /api/notifications/multi-user-grace/cron, daily 07:00 UTC.
+ *
+ * Mails company owners when the multi_user grace window opens (their extra
+ * members will pause in 20 days) and again on its last day. Windowed on the
+ * grant expiry timestamps so a once-daily run sends each mail exactly once;
+ * see lib/notifications/multi-user-grace.ts.
+ */
+export const GET = withCronContext('cron.multi_user_grace', async (_request, ctx) => {
+  const supabase = createServiceClient()
+  const summary = await runMultiUserGraceReminders(supabase, new Date())
+
+  ctx.log.info('multi-user grace reminder summary', { ...summary })
+
+  return NextResponse.json({ success: true, ...summary })
+})
+
+export const POST = GET
+
+/** A grants scan plus a handful of emails. */
+export const maxDuration = 300