Pular para o conteúdo principal

SaaS Tiers + Billing — Stripe-powered multi-tenant

A partir da v4.8, o CipherVault inclui scaffolding completo de SaaS multi-tenant pra hospedagem em https://cv.ciphervault.com.br:

  • Stripe billing foundation (products, prices, webhooks)
  • Public signup + email verify
  • Tier enforcement middleware feature-gated
  • Status page scaffold + operator runbook
  • Legal templates (SLA, DPA GDPR Art. 28, ToS, Privacy)

Este doc cobre a stack pra quem quer self-host como SaaS (multi-tenant com billing) ou integrar com Stripe próprio.

Tiers​

TierLimites (default)Features
free1 user, 1 vault, 25 secretsCore vault + RBAC + MFA
starter5 users, 3 vaults, 250 secrets+ SIEM, multi-cloud, audit retention 30d
professional25 users, 10 vaults, 2500 secrets+ Dynamic Secrets, attack paths, Browser Extension, Copilot básico
enterpriseunlimited+ Tudo (Fortress, PKI, EaaS, SSH CA, ZK, PQC V2, KMIP, Guardian, dual-control N-de-M, custom SLA)

Override de limites per-tenant via admin (PATCH /tenants/:id com limits object).

Stripe billing foundation (#324)​

  • products + prices sincronizados via Stripe Dashboard
  • Webhook POST /billing/webhook consome customer.subscription.{created,updated,deleted}, invoice.{paid,payment_failed}
  • Customer→tenant mapping em stripe_customers table
  • Subscription lifecycle em subscriptions (status: active, past_due, canceled, incomplete)

Endpoints​

GET    /billing/subscriptions                     Lista do tenant
GET    /billing/subscriptions/:id
POST   /billing/subscriptions/:id/bind-tenant     Admin link Stripe→tenant
POST   /billing/webhook                           Stripe → CV (signed)
POST   /billing/checkout-session                  Inicia Stripe Checkout
POST   /billing/portal-session                    Portal Stripe (cancel/update card)

Config​

export STRIPE_SECRET_KEY=sk_live_...
export STRIPE_WEBHOOK_SECRET=whsec_...
export STRIPE_PRICE_STARTER=price_...
export STRIPE_PRICE_PROFESSIONAL=price_...
export STRIPE_PRICE_ENTERPRISE=price_...

Public signup (#325, #328)​

Self-service onboarding. Não exige admin existing.

Flow​

  1. POST /saas/signup { email, password, tenant_name }
    • Cria tenant + user (não verificado)
    • Envia email com verify_token (24h TTL)
  2. GET /verify-email/:token ativa account
  3. (Opcional) POST /resend-verification
  4. Redirect pra Stripe Checkout se tier > free

UI​

/signup (v4.8) — landing form → Stripe Checkout → activate tenant → dashboard.

Tier enforcement (#326)​

Middleware requireTier(...) em routes feature-gated:

router.post('/dynamic-secrets/...',
  requireAuth,
  requireTier('professional'),  // ← starter recebe 403
  asyncHandler(...));

Endpoints​

GET  /saas/tiers          Lista pública dos tiers + features + price
GET  /saas/tier           Tier atual do tenant + quotas atuais + grace

Response:

{
  "tier": "professional",
  "limits": { "users": 25, "vaults": 10, "secrets": 2500 },
  "usage":  { "users": 18, "vaults": 7, "secrets": 1234 },
  "grace_period_ends_at": null,
  "downgrade_eligible_at": "2026-06-15"
}

Grace period​

Subscription past_due ou canceled entra em grace period 7d configurável. Durante grace:

  • Read-only access permanece
  • Writes bloqueados com mensagem clara
  • Email diário até resolver
  • Após grace: tenant suspended (data preserved 30d, então purge)

Status page scaffold (#327)​

Operator runbook em docs/runbooks/SAAS_OPERATIONS.md cobre:

  • Onboard tenant manualmente (sem Stripe, pra POC/trial)
  • Suspend/unsuspend
  • Tenant purge depois de 30d
  • Migration de tenant (export → import em outro deployment)
  • Reset de billing state em case de stripe sync desync

Status page mínima em /status (HTML estático, sem auth) com 4 cards (API, DB, Billing, Copilot) lendo Prometheus.

Em etc/legal/ do produto:

DocNotes
SLA.template.md99.5% / 99.9% / 99.95% tiers, credit schedule, exclusions
DPA.template.mdGDPR Art. 28 Data Processing Agreement + sub-processor list
ToS.template.mdBrasileiro com cláusulas LGPD + foro
PRIVACY.template.mdPrivacy policy LGPD + GDPR híbrida

Placeholders por jurisdição (BR / EU / US). Não substitui review por advogado da sua empresa.

Tenants UI (#276 v4.7)​

  • Suspend / unsuspend actions com confirmation typed
  • Purge countdown visível
  • Suspended reason inline
  • Quota gauges color-coded por threshold (>80% warning, >95% critical)

Limitações​

  • No annual billing UI ainda — Stripe Checkout pode, mas signup atual force monthly
  • No usage-based billing — flat tiers. Roadmap: secret-count meter
  • No multi-currency — USD only. Stripe suporta, integration pendente
  • No trial via Stripe — trials hoje via admin manual (free tier ilimitado tempo)

Self-host: tenants sem billing​

Quem só quer multi-tenant sem Stripe (ex: deploy interno corporate), desabilita billing:

export CV_BILLING_ENABLED=false
export CV_DEFAULT_TIER=enterprise  # cada tenant nasce enterprise

Middleware requireTier(...) continua functioning (vê env e short-circuits).

Referências​

  • backend/src/routes/saas-{billing,signup,tier}.js no repo do produto
  • etc/legal/*.template.md
  • Issue #268 — epic
  • Blog post v4.8