feat(entitlements): per-company capability paywall — gate, trial seeding, UI upsells, Stripe checkout (#815)

* feat(entitlements): capability-grant gate substrate (paywall + modularity)

Two-axis capability primitive behind the SaaS paywall and the per-tenant
modularity/marketplace vision:
- migration: capability_grants (entitlement axis, polymorphic company/firm
  scope), company_capability_config (enablement axis), metered_events
  (append-only), company_has_capability() RPC reusing the 20260619130100
  tenant guard; SELECT-only RLS (writes service-role only, no self-grant).
- lib/entitlements: hasCapability/requireCapability gate (mirrors guardSandbox,
  fail-closed, NEXT_PUBLIC_SELF_HOSTED bypass), capability key namespace,
  metering helper.
- unit (11) + pg-real tests (RPC/RLS/tenant-guard incl. no-self-grant).

Gate not yet wired into call sites (follow-up commit). Paid keys:
ai, bank_sync, skatteverket, email_send.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(entitlements): enforce capability gate at paid external-service chokepoints

Wire the gate into the paid surfaces (keys: ai, email_send, bank_sync, skatteverket):
- AI routes (agent invoke/composer/onboarding stream): requireCapability(ai)
- Invoice send (web + v1): requireCapability(email_send)
- document-extraction event handler: skip Bedrock extract if ai not entitled
- enable-banking + skatteverket crons: per-company hasCapability skip in loop
- colocated send-route test mocks updated (requireCapability -> null)

Free per founder decision: TIC org lookup, VIES VAT validation, FX auto-fetch,
cloud backup, BankID login, all internal bookkeeping.

DEPLOY ORDER: fail-closed by design — do NOT deploy before trial/comp grant
seeding lands, or companies without grants lose these features. Seeding +
Stripe checkout/webhook are the next steps.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(entitlements): seed trial + comp capability grants

Makes the fail-closed gate safely deployable — nobody is locked out at cutover:
- AFTER INSERT trigger on companies grants every NEW company a 30-day trial on
  the PAID keys (ai, bank_sync, skatteverket, email_send), on ALL creation paths
  (RPC/MCP/direct) — so a new signup can use onboarding AI immediately.
- one-time backfill for EXISTING companies: created <=2026-06-07 -> trial ends
  2026-07-07; created later -> created_at + 30 days.
- permanent comp grants for Arcim/Mattsson (matched by name, no hardcoded UUIDs).
- pg tests: clearGrants() for controlled resolver tests + trigger coverage.

Trigger fn is SECURITY DEFINER so it writes grants regardless of caller RLS
(table has no INSERT policy for authenticated — no self-grant).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(entitlements): client capability visibility + billing page

Non-payers get a clean upsell instead of broken/empty features:
- CompanyContext gains capabilities[] + useCapability(key); resolved once
  server-side in the dashboard layout via getCompanyCapabilities (batched, 2
  queries), all three provider branches wired.
- /settings/billing upgrade page — the destination upsells point to (Stripe
  Payment Link via NEXT_PUBLIC_STRIPE_PAYMENT_LINK; degrades to 'coming soon'
  until automated checkout lands).
- ChatEmptyState: non-payer sees an Uppgradera CTA (mirrors the sandbox state).
- SendInvoiceDialog: email send disabled + upsell note when email_send missing
  (extends the existing sandbox-disable pattern).

Fast-follow: chat input/FAB + document-inbox empty state + bank/skatteverket/
AI-suggest buttons + a shared capability_blocked->toast backstop.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(entitlements): gate remaining paid UI surfaces with upsell (fast-follow)

disable-with-upsell across the rest of the paid surfaces (keys: bank_sync, skatteverket, ai):
- BankSyncNowButton: sync/reconnect disabled + note when !bank_sync (CSV/SIE stays free)
- AGIPanel: AGI submit-to-Skatteverket disabled + note when !skatteverket
- SkatteverketConnectPanel: BankID connect/reconnect disabled + upsell
- ApprovalCard: AI re-propose (correction) gated; manual approve/reject stay free
- InvoiceInboxWorkspace: upsell when extraction empty AND !ai (deterministic parse + manual entry unaffected)
- AgentTrigger FAB: routes to /settings/billing when !ai (no dead chat)
- settings nav: 'Abonnemang'/'Subscription' link to /settings/billing (sv/en)

TaxPaymentPanel + TransactionInboxCard intentionally untouched — only local/
deterministic actions there, nothing paid+external to gate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(entitlements): automated Stripe subscription checkout + webhook

Self-serve revenue wired to the same capability-grant primitive:
- migration: company_subscriptions (company<->Stripe link/status) + stripe_webhook_events (idempotency)
- lib/stripe: getStripe singleton, plan->price mapping, subscription-sync (statusGrantsAccess / subscriptionToState / applySubscriptionState / handleStripeEvent). Active sub -> upsert source='stripe' grants for PAID keys (expiry = period_end + 3d grace); canceled/unpaid -> remove ONLY stripe grants (freeze-and-retain).
- routes: POST /api/billing/checkout (hosted subscription Checkout, company_id metadata), POST /api/billing/portal (Customer Portal), POST /api/stripe/webhook (raw-body signature verify, event-id dedup; handles checkout.session.completed + customer.subscription.*)
- billing page: real plan-toggle Checkout CTA / manage-subscription portal, gated on isStripeConfigured()
- adds stripe@22; unit tests for sync logic

Provisioning is webhook-driven (never trusts the success redirect). Needs env: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_MONTHLY, STRIPE_PRICE_YEARLY.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(entitlements): validate UUIDs in capability filter + log webhook errors

Addresses PR review (Superagent Security / PR Agent):
- has-capability.ts: validate companyId/teamId as UUIDs before interpolating into the PostgREST .or() filter (fail-closed) — removes the latent injection vector flagged in the entitlement gate. Unit tests updated to use UUIDs.
- stripe/webhook: log processing failures with event id + type before the generic 500, so a failing webhook is visible to operators.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(salary): always-free AGI XML download for manual filing; only direct API submit is paid

Per founder decision on the swedish-compliance-review finding: AGI is a mandatory statutory filing, so producing/downloading the AGI XML must never be paywalled. Adds a free 'Ladda ner AGI-fil' button (generates + downloads the XML for manual upload to Skatteverket's e-service) on all tiers; the gated 'Skicka in underlag' stays the paid convenience (direct API submission — which also requires the paid BankID connection). Upsell reworded to point to the manual path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(entitlements): harden comp-grant match after prod verification

Verified Arcim/Mattsson in prod (pwxtzglxptnnvjrpixpg): the name match was case-sensitive (missed the active 'Arcim technology AB' lowercase variant) and would have granted 3 archived dupes. Now match by org_number (5595386219 / 5595719864) OR case-insensitive name, active companies only — hits exactly the 3 active comp companies, excludes archived dupes and the unrelated 'Amnäs Mattsson, Emil' enskild firma.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/api/billing/checkout/route.ts

@@ -0,0 +1,66 @@
+import { NextResponse } from 'next/server'
+import { requireAuth } from '@/lib/auth/require-auth'
+import { requireCompanyId } from '@/lib/company/context'
+import { createServiceClient } from '@/lib/supabase/server'
+import { getStripe, priceIdForPlan, type BillingPlan } from '@/lib/stripe/client'
+
+/**
+ * Create a Stripe subscription Checkout Session and return its hosted URL.
+ * The client redirects to it; provisioning happens via the webhook on
+ * checkout.session.completed (never trust the success redirect for fulfilment).
+ */
+export async function POST(request: Request) {
+  const { user, supabase, error } = await requireAuth()
+  if (error) return error
+
+  let companyId: string
+  try {
+    companyId = await requireCompanyId(supabase, user.id)
+  } catch {
+    return NextResponse.json({ error: 'No company context' }, { status: 400 })
+  }
+
+  const body = (await request.json().catch(() => ({}))) as { plan?: string }
+  const plan: BillingPlan = body.plan === 'yearly' ? 'yearly' : 'monthly'
+  const priceId = priceIdForPlan(plan)
+  if (!priceId) {
+    return NextResponse.json({ error: 'Stripe price not configured' }, { status: 500 })
+  }
+
+  const stripe = getStripe()
+  const service = createServiceClient()
+
+  // Reuse the company's Stripe customer if we already created one.
+  const { data: existing } = await service
+    .from('company_subscriptions')
+    .select('stripe_customer_id')
+    .eq('company_id', companyId)
+    .maybeSingle()
+
+  let customerId = (existing as { stripe_customer_id: string | null } | null)?.stripe_customer_id ?? null
+  if (!customerId) {
+    const customer = await stripe.customers.create({
+      email: user.email ?? undefined,
+      metadata: { company_id: companyId },
+    })
+    customerId = customer.id
+    await service
+      .from('company_subscriptions')
+      .upsert({ company_id: companyId, stripe_customer_id: customerId }, { onConflict: 'company_id' })
+  }
+
+  const appUrl = process.env.NEXT_PUBLIC_APP_URL ?? ''
+  const session = await stripe.checkout.sessions.create({
+    mode: 'subscription',
+    customer: customerId,
+    line_items: [{ price: priceId, quantity: 1 }],
+    client_reference_id: companyId,
+    metadata: { company_id: companyId },
+    subscription_data: { metadata: { company_id: companyId } },
+    allow_promotion_codes: true,
+    success_url: `${appUrl}/settings/billing?success=1`,
+    cancel_url: `${appUrl}/settings/billing?canceled=1`,
+  })
+
+  return NextResponse.json({ url: session.url })
+}

app/api/billing/portal/route.ts

@@ -0,0 +1,42 @@
+import { NextResponse } from 'next/server'
+import { requireAuth } from '@/lib/auth/require-auth'
+import { requireCompanyId } from '@/lib/company/context'
+import { createServiceClient } from '@/lib/supabase/server'
+import { getStripe } from '@/lib/stripe/client'
+
+/**
+ * Create a Stripe Billing Customer Portal session so the user can manage,
+ * upgrade/downgrade, or cancel their subscription. Stripe handles all the
+ * compliance/PCI surface — we never build those flows ourselves.
+ */
+export async function POST() {
+  const { user, supabase, error } = await requireAuth()
+  if (error) return error
+
+  let companyId: string
+  try {
+    companyId = await requireCompanyId(supabase, user.id)
+  } catch {
+    return NextResponse.json({ error: 'No company context' }, { status: 400 })
+  }
+
+  const service = createServiceClient()
+  const { data: sub } = await service
+    .from('company_subscriptions')
+    .select('stripe_customer_id')
+    .eq('company_id', companyId)
+    .maybeSingle()
+
+  const customerId = (sub as { stripe_customer_id: string | null } | null)?.stripe_customer_id
+  if (!customerId) {
+    return NextResponse.json({ error: 'No subscription to manage' }, { status: 400 })
+  }
+
+  const appUrl = process.env.NEXT_PUBLIC_APP_URL ?? ''
+  const portal = await getStripe().billingPortal.sessions.create({
+    customer: customerId,
+    return_url: `${appUrl}/settings/billing`,
+  })
+
+  return NextResponse.json({ url: portal.url })
+}