feat(billing): add FeatureGate, UpgradePrompt, EmailVerificationGate components

Three drop-in gating components for the self-serve signup flow.

- FeatureGate reads useFeature(flag) and renders children when enabled,
  else a fallback (default UpgradePrompt). UX-only — security boundary
  remains require_feature on the backend.
- UpgradePrompt resolves a feature key to display name + required plan
  via an inline catalog and links to /account/billing/select-plan.
- EmailVerificationGate gates protected content behind a 6-day grace
  period; renders a minimal EmailVerificationWall (resend + sign out)
  on Day 7+ unverified. Wall design will be refined in Task 37.

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

frontend/src/components/common/EmailVerificationGate.tsx

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react'
+import { useAuthStore } from '@/store/authStore'
+import { EmailVerificationWall } from './EmailVerificationWall'
+
+interface EmailVerificationGateProps {
+  children: ReactNode
+  /**
+   * Override the grace period (in days). Day `gracePeriodDays + 1` and beyond
+   * trigger the wall. Defaults to 6 — the spec says Day 1–6 unverified renders
+   * children and Day 7+ renders the wall.
+   */
+  gracePeriodDays?: number
+}
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000
+
+/** Whole days elapsed between two ISO timestamps (floored). */
+function daysSince(iso: string, now: number = Date.now()): number {
+  const created = Date.parse(iso)
+  if (Number.isNaN(created)) {
+    // Defensive: bad timestamp — treat as just-signed-up so we don't
+    // accidentally lock anyone out.
+    return 0
+  }
+  return Math.floor((now - created) / MS_PER_DAY)
+}
+
+/**
+ * Wraps protected content. While the current user is past the grace period
+ * without having verified their email, renders `<EmailVerificationWall />`
+ * instead of children.
+ *
+ * Behavior:
+ * - No user (signed out): renders children (let route guards handle auth).
+ * - User has `email_verified_at`: renders children.
+ * - Day 1–6 unverified: renders children (banner is shown elsewhere).
+ * - Day 7+ unverified: renders the wall.
+ */
+export function EmailVerificationGate({
+  children,
+  gracePeriodDays = 6,
+}: EmailVerificationGateProps) {
+  const user = useAuthStore((s) => s.user)
+
+  if (!user) return <>{children}</>
+  if (user.email_verified_at) return <>{children}</>
+
+  const elapsed = daysSince(user.created_at)
+  if (elapsed > gracePeriodDays) {
+    return <EmailVerificationWall />
+  }
+
+  return <>{children}</>
+}
+
+export default EmailVerificationGate

frontend/src/components/common/EmailVerificationWall.tsx

@@ -0,0 +1,88 @@
+import { useState } from 'react'
+import { Loader2, MailCheck } from 'lucide-react'
+import { authApi } from '@/api/auth'
+import { useAuthStore } from '@/store/authStore'
+import { toast } from '@/lib/toast'
+import { cn } from '@/lib/utils'
+
+interface EmailVerificationWallProps {
+  className?: string
+}
+
+/**
+ * Hard wall shown after the email-verification grace period expires.
+ *
+ * Minimal v1 — Task 37 will refine copy, layout, and add the
+ * `/verify-email?token=...` route handling. Until then this gives
+ * Day 7+ unverified users a way to re-send the verification email
+ * or sign out.
+ */
+export function EmailVerificationWall({ className }: EmailVerificationWallProps) {
+  const user = useAuthStore((s) => s.user)
+  const logout = useAuthStore((s) => s.logout)
+  const [isSending, setIsSending] = useState(false)
+
+  const handleResend = async () => {
+    setIsSending(true)
+    try {
+      await authApi.sendVerificationEmail()
+      toast.success('Verification email sent')
+    } catch {
+      toast.error('Failed to send verification email')
+    } finally {
+      setIsSending(false)
+    }
+  }
+
+  const handleLogout = async () => {
+    try {
+      await logout()
+    } catch {
+      // logout swallows API errors internally
+    }
+  }
+
+  return (
+    <div
+      className={cn(
+        'flex min-h-[60vh] items-center justify-center px-4 py-12',
+        className,
+      )}
+      data-testid="email-verification-wall"
+    >
+      <div className="w-full max-w-md rounded-lg border border-default bg-card p-6 text-center">
+        <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-full border border-default bg-elevated text-muted-foreground">
+          <MailCheck className="h-5 w-5" aria-hidden="true" />
+        </div>
+        <h2 className="text-lg font-semibold text-heading">
+          Verify your email to continue
+        </h2>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {user?.email
+            ? `We sent a verification link to ${user.email}. Click it to unlock your account.`
+            : 'Check your inbox for the verification link we sent when you signed up.'}
+        </p>
+        <div className="mt-6 flex flex-col gap-2">
+          <button
+            type="button"
+            onClick={handleResend}
+            disabled={isSending}
+            className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90 disabled:opacity-50"
+          >
+            {isSending && <Loader2 className="h-4 w-4 animate-spin" />}
+            Resend verification email
+          </button>
+          <button
+            type="button"
+            onClick={handleLogout}
+            className="rounded-md border border-default bg-elevated px-4 py-2 text-sm font-medium text-primary transition-colors hover:bg-white/[0.06]"
+          >
+            Sign out
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default EmailVerificationWall

frontend/src/components/common/FeatureGate.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react'
+import { useFeature } from '@/hooks/useFeature'
+import { UpgradePrompt } from './UpgradePrompt'
+
+interface FeatureGateProps {
+  /** Feature flag key (e.g. `psa_integration`). Must match a backend `feature_flags.flag_key`. */
+  feature: string
+  /**
+   * Rendered when the feature is enabled for the current account.
+   */
+  children: ReactNode
+  /**
+   * Rendered when the feature is disabled. Defaults to `<UpgradePrompt feature={feature} />`.
+   * Pass `null` to render nothing.
+   */
+  fallback?: ReactNode
+}
+
+/**
+ * Conditionally renders `children` based on whether `feature` is enabled
+ * for the current account.
+ *
+ * This is a UX affordance — the security boundary is the backend
+ * `require_feature` dependency. Never trust this gate for authorization.
+ */
+export function FeatureGate({ feature, children, fallback }: FeatureGateProps) {
+  const enabled = useFeature(feature)
+
+  if (enabled) {
+    return <>{children}</>
+  }
+
+  // Use explicit fallback when provided, otherwise render the standard prompt.
+  // `null` is a valid fallback (renders nothing).
+  if (fallback !== undefined) {
+    return <>{fallback}</>
+  }
+
+  return <UpgradePrompt feature={feature} />
+}
+
+export default FeatureGate

frontend/src/components/common/UpgradePrompt.tsx

@@ -0,0 +1,111 @@
+import { Lock, Sparkles } from 'lucide-react'
+import { Link } from 'react-router-dom'
+import { cn } from '@/lib/utils'
+
+interface UpgradePromptProps {
+  feature: string
+  className?: string
+}
+
+interface FeatureMeta {
+  /** Display name shown in the prompt heading. */
+  displayName: string
+  /** Plan that unlocks this feature. */
+  requiredPlan: string
+  /** Optional one-line value pitch. */
+  description?: string
+}
+
+/**
+ * Mapping from feature flag key to display metadata.
+ *
+ * v1: small inline table maintained here. If this grows, lift to
+ * `frontend/src/lib/featureCatalog.ts` and source from a backend endpoint.
+ *
+ * Keys must match `feature_flags.flag_key` on the backend.
+ */
+const FEATURE_CATALOG: Record<string, FeatureMeta> = {
+  psa_integration: {
+    displayName: 'PSA Integration',
+    requiredPlan: 'Pro',
+    description: 'Sync tickets and assets with your PSA in real time.',
+  },
+  kb_accelerator: {
+    displayName: 'Knowledge Base Accelerator',
+    requiredPlan: 'Pro',
+    description: 'Auto-generate troubleshooting flows from your existing KB.',
+  },
+  ai_builder: {
+    displayName: 'AI Builder',
+    requiredPlan: 'Pro',
+    description: 'Generate decision trees from natural-language prompts.',
+  },
+  branching_logic: {
+    displayName: 'Branching Logic',
+    requiredPlan: 'Pro',
+  },
+  custom_branding: {
+    displayName: 'Custom Branding',
+    requiredPlan: 'Pro',
+  },
+  api_access: {
+    displayName: 'API Access',
+    requiredPlan: 'Pro',
+  },
+  sso: {
+    displayName: 'Single Sign-On',
+    requiredPlan: 'Enterprise',
+  },
+}
+
+/** Humanize an unknown feature key for the fallback display name. */
+function humanizeFeatureKey(key: string): string {
+  return key
+    .split('_')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+/**
+ * Standardized "this feature is on Pro" affordance.
+ *
+ * Renders a locked panel with a CTA that routes to the plan-selection page.
+ * The actual gating is enforced server-side via `require_feature` — this is UX.
+ */
+export function UpgradePrompt({ feature, className }: UpgradePromptProps) {
+  const meta = FEATURE_CATALOG[feature]
+  const displayName = meta?.displayName ?? humanizeFeatureKey(feature)
+  const requiredPlan = meta?.requiredPlan ?? 'Pro'
+  const description = meta?.description
+
+  return (
+    <div
+      className={cn(
+        'flex flex-col items-center justify-center gap-3 rounded-lg border border-default bg-white/[0.04] px-6 py-10 text-center',
+        className,
+      )}
+      data-testid="upgrade-prompt"
+    >
+      <div className="flex h-10 w-10 items-center justify-center rounded-full border border-default bg-elevated text-muted-foreground">
+        <Lock className="h-4 w-4" aria-hidden="true" />
+      </div>
+      <div className="space-y-1">
+        <h3 className="text-base font-semibold text-heading">
+          {displayName} is available on {requiredPlan}
+        </h3>
+        {description && (
+          <p className="max-w-md text-sm text-muted-foreground">{description}</p>
+        )}
+      </div>
+      <Link
+        to="/account/billing/select-plan"
+        className="inline-flex items-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
+      >
+        <Sparkles className="h-4 w-4" aria-hidden="true" />
+        Upgrade to {requiredPlan}
+      </Link>
+    </div>
+  )
+}
+
+export default UpgradePrompt

frontend/src/components/common/__tests__/EmailVerificationGate.test.tsx

@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { BrowserRouter } from 'react-router-dom'
+import { EmailVerificationGate } from '../EmailVerificationGate'
+import { useAuthStore } from '@/store/authStore'
+import type { User } from '@/types'
+
+function makeUser(overrides: Partial<User> = {}): User {
+  return {
+    id: 'user-1',
+    email: 'test@example.com',
+    name: 'Test User',
+    role: 'engineer',
+    is_super_admin: false,
+    is_active: true,
+    must_change_password: false,
+    account_id: 'acct-1',
+    account_role: 'engineer',
+    team_id: null,
+    created_at: '2026-05-01T00:00:00Z',
+    last_login: null,
+    phone: null,
+    job_title: null,
+    timezone: 'UTC',
+    avatar_url: null,
+    email_verified_at: null,
+    ...overrides,
+  }
+}
+
+const FROZEN_NOW = new Date('2026-05-06T00:00:00Z')
+
+function renderWithRouter(ui: React.ReactElement) {
+  return render(<BrowserRouter>{ui}</BrowserRouter>)
+}
+
+describe('EmailVerificationGate', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(FROZEN_NOW)
+    useAuthStore.setState({ user: null, token: null, isAuthenticated: false })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('renders children when no user is signed in', () => {
+    renderWithRouter(
+      <EmailVerificationGate>
+        <div>protected</div>
+      </EmailVerificationGate>,
+    )
+    expect(screen.getByText('protected')).toBeInTheDocument()
+  })
+
+  it('renders children when user has verified email', () => {
+    useAuthStore.setState({
+      user: makeUser({ email_verified_at: '2026-04-01T00:00:00Z' }),
+    })
+    renderWithRouter(
+      <EmailVerificationGate>
+        <div>protected</div>
+      </EmailVerificationGate>,
+    )
+    expect(screen.getByText('protected')).toBeInTheDocument()
+  })
+
+  it('renders children on day 1 unverified (within grace)', () => {
+    // created 1 day before frozen now.
+    useAuthStore.setState({
+      user: makeUser({ created_at: '2026-05-05T00:00:00Z' }),
+    })
+    renderWithRouter(
+      <EmailVerificationGate>
+        <div>protected</div>
+      </EmailVerificationGate>,
+    )
+    expect(screen.getByText('protected')).toBeInTheDocument()
+  })
+
+  it('renders children on day 6 unverified (last day of grace)', () => {
+    // created 6 days before frozen now.
+    useAuthStore.setState({
+      user: makeUser({ created_at: '2026-04-30T00:00:00Z' }),
+    })
+    renderWithRouter(
+      <EmailVerificationGate>
+        <div>protected</div>
+      </EmailVerificationGate>,
+    )
+    expect(screen.getByText('protected')).toBeInTheDocument()
+  })
+
+  it('renders wall on day 7 unverified user', () => {
+    // created 7 days before frozen now -> elapsed=7, > grace=6 -> wall.
+    useAuthStore.setState({
+      user: makeUser({ created_at: '2026-04-29T00:00:00Z' }),
+    })
+    renderWithRouter(
+      <EmailVerificationGate>
+        <div>protected</div>
+      </EmailVerificationGate>,
+    )
+    expect(screen.queryByText('protected')).not.toBeInTheDocument()
+    expect(screen.getByTestId('email-verification-wall')).toBeInTheDocument()
+    expect(screen.getByText(/Verify your email to continue/i)).toBeInTheDocument()
+  })
+
+  it('renders wall on day 8 unverified user', () => {
+    // created 8 days before frozen now.
+    useAuthStore.setState({
+      user: makeUser({ created_at: '2026-04-28T00:00:00Z' }),
+    })
+    renderWithRouter(
+      <EmailVerificationGate>
+        <div>protected</div>
+      </EmailVerificationGate>,
+    )
+    expect(screen.queryByText('protected')).not.toBeInTheDocument()
+    expect(screen.getByTestId('email-verification-wall')).toBeInTheDocument()
+  })
+})

frontend/src/components/common/__tests__/FeatureGate.test.tsx

@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { BrowserRouter } from 'react-router-dom'
+import { FeatureGate } from '../FeatureGate'
+import { useBillingStore } from '@/store/billingStore'
+
+function renderWithRouter(ui: React.ReactElement) {
+  return render(<BrowserRouter>{ui}</BrowserRouter>)
+}
+
+describe('FeatureGate', () => {
+  beforeEach(() => {
+    useBillingStore.setState({
+      subscription: null,
+      planBilling: null,
+      planLimits: {},
+      enabledFeatures: {},
+      isLoading: false,
+      error: null,
+    })
+  })
+
+  it('renders children when flag enabled, fallback when disabled', () => {
+    // Disabled by default — renders default UpgradePrompt fallback.
+    const { unmount } = renderWithRouter(
+      <FeatureGate feature="psa_integration">
+        <div>protected content</div>
+      </FeatureGate>,
+    )
+    expect(screen.queryByText('protected content')).not.toBeInTheDocument()
+    expect(screen.getByTestId('upgrade-prompt')).toBeInTheDocument()
+    unmount()
+
+    // Enabled — renders children.
+    useBillingStore.setState({ enabledFeatures: { psa_integration: true } })
+    renderWithRouter(
+      <FeatureGate feature="psa_integration">
+        <div>protected content</div>
+      </FeatureGate>,
+    )
+    expect(screen.getByText('protected content')).toBeInTheDocument()
+    expect(screen.queryByTestId('upgrade-prompt')).not.toBeInTheDocument()
+  })
+
+  it('renders custom fallback when disabled', () => {
+    renderWithRouter(
+      <FeatureGate
+        feature="psa_integration"
+        fallback={<div>custom fallback</div>}
+      >
+        <div>protected</div>
+      </FeatureGate>,
+    )
+    expect(screen.getByText('custom fallback')).toBeInTheDocument()
+    expect(screen.queryByText('protected')).not.toBeInTheDocument()
+  })
+
+  it('renders nothing when fallback is null and feature disabled', () => {
+    const { container } = renderWithRouter(
+      <FeatureGate feature="psa_integration" fallback={null}>
+        <div>protected</div>
+      </FeatureGate>,
+    )
+    expect(screen.queryByText('protected')).not.toBeInTheDocument()
+    expect(container.textContent).toBe('')
+  })
+})

frontend/src/components/common/__tests__/UpgradePrompt.test.tsx

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { BrowserRouter } from 'react-router-dom'
+import { UpgradePrompt } from '../UpgradePrompt'
+
+function renderWithRouter(ui: React.ReactElement) {
+  return render(<BrowserRouter>{ui}</BrowserRouter>)
+}
+
+describe('UpgradePrompt', () => {
+  it('renders display name and required plan from catalog', () => {
+    renderWithRouter(<UpgradePrompt feature="psa_integration" />)
+    expect(
+      screen.getByText(/PSA Integration is available on Pro/i),
+    ).toBeInTheDocument()
+  })
+
+  it('CTA navigates to /account/billing/select-plan', () => {
+    renderWithRouter(<UpgradePrompt feature="psa_integration" />)
+    const cta = screen.getByRole('link', { name: /Upgrade to Pro/i })
+    expect(cta).toHaveAttribute('href', '/account/billing/select-plan')
+  })
+
+  it('humanizes unknown feature keys and falls back to Pro', () => {
+    renderWithRouter(<UpgradePrompt feature="some_new_feature" />)
+    expect(
+      screen.getByText(/Some New Feature is available on Pro/i),
+    ).toBeInTheDocument()
+  })
+})