quantictech-subscription-components/SECURITY.md

Biblioteca de componentes reutilizáveis para sistema de assinatura com Stripe - Arquitetura Service-to-Service

# 🔒 Guia de Segurança

## 🛡️ O que é Seguro na Biblioteca

### ✅ Conteúdo SEGURO (está na biblioteca):
- Componentes React (interface)
- Hooks personalizados 
- Funções utilitárias (formatação)
- Tipos TypeScript
- Templates de código (para copiar)

### ❌ O que NUNCA está na biblioteca:
- Chaves secretas do Stripe
- Tokens de autenticação  
- Dados de usuários
- Informações de pagamento
- Credenciais de banco de dados

## 🔐 Como Manter a Segurança

### 1. Variáveis de Ambiente (Por Projeto)

Cada projeto deve ter suas próprias variáveis:

```bash
# .env.local (cada projeto)
STRIPE_SECRET_KEY=sk_test_SUA_CHAVE_SECRETA_UNICA
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_SUA_CHAVE_PUBLICA_UNICA
STRIPE_WEBHOOK_SECRET=whsec_SEU_WEBHOOK_SECRET_UNICO
```

**⚠️ NUNCA faça:**
```typescript
// ❌ NUNCA hardcode chaves na biblioteca
const stripe = new Stripe('sk_test_123456789'); // PERIGOSO!

// ✅ SEMPRE use variáveis de ambiente
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY); // SEGURO!
```

### 2. APIs Independentes (Por Projeto)

```bash
# ✅ Templates são COPIADOS (não centralizados)
cp templates/webhook-api/* pages/api/

# Cada projeto tem suas próprias APIs em:
meu-projeto-1/pages/api/webhook.ts
meu-projeto-2/pages/api/webhook.ts
```

### 3. Lógica de Negócio Separada

```typescript
// ✅ Cada projeto implementa sua lógica
async function handleSubscriptionCreated(subscription) {
  // Conecta ao SEU banco específico
  await YOUR_DATABASE.subscriptions.create({
    stripeId: subscription.id,
    userId: subscription.metadata.userId
  });
  
  // Envia email com SUA configuração
  await YOUR_EMAIL_SERVICE.send({
    to: subscription.metadata.customerEmail,
    template: 'welcome'
  });
}
```

## 🚨 Checklist de Segurança

### Para a Biblioteca:
- [ ] ✅ Não contém chaves hardcoded
- [ ] ✅ Usa apenas process.env para acessar variáveis
- [ ] ✅ Templates são apenas código para copiar
- [ ] ✅ Não executa lógica de negócio sensível

### Para Cada Projeto:
- [ ] ✅ Variáveis de ambiente configuradas
- [ ] ✅ Chaves diferentes para dev/prod
- [ ] ✅ APIs copiadas e customizadas
- [ ] ✅ Webhooks configurados corretamente
- [ ] ✅ Logs não exposem dados sensíveis

## 🌐 Publicação Segura

### Biblioteca Pública é SEGURA porque:

1. **Não há dados sensíveis** - apenas código de interface
2. **Cada projeto é independente** - suas próprias chaves e APIs
3. **Templates não executam** - são apenas modelos para copiar
4. **Padrão da indústria** - MUI, Stripe SDK são públicos

### Exemplo de bibliotecas públicas similares:
- `@stripe/react-stripe-js` (oficial do Stripe)
- `@mui/material` (interface)
- `next` (framework)

## 🔄 Boas Práticas

### 1. Rotação de Chaves
```bash
# Mude periodicamente as chaves do Stripe
STRIPE_SECRET_KEY=sk_test_nova_chave_123
```

### 2. Ambientes Separados
```bash
# Desenvolvimento
STRIPE_SECRET_KEY=sk_test_...

# Produção  
STRIPE_SECRET_KEY=sk_live_...
```

### 3. Monitoramento
```bash
# Monitore logs do Stripe
Dashboard → Webhooks → View logs
Dashboard → Payments → View details
```

### 4. Validação de Webhooks
```typescript
// ✅ Sempre valide a assinatura do webhook
const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(body, sig, endpointSecret);
```

## ⚡ Vantagens da Biblioteca Pública

### Segurança:
- ✅ Código auditável pela comunidade
- ✅ Updates de segurança automáticos
- ✅ Padrões da indústria

### Manutenção:
- ✅ Correções centralizadas
- ✅ Melhorias automáticas via `npm update`
- ✅ Comunidade pode contribuir

### Desenvolvimento:
- ✅ Setup rápido em novos projetos
- ✅ Documentação centralizada
- ✅ Exemplos de uso

## 🚨 Quando NÃO usar biblioteca pública

- ❌ Se você hardcoda informações sensíveis (mas isso seria má prática)
- ❌ Se tem lógica de negócio muito proprietária (mas isso deveria estar no projeto, não na lib)
- ❌ Se precisa de controle total sobre quem usa (rare casos corporativos)

## ✅ Conclusão

**A biblioteca É SEGURA para ser pública** porque:

1. Contém apenas código de interface
2. Não executa lógica sensível
3. Cada projeto mantém suas próprias chaves
4. Segue padrões da indústria (Stripe, MUI, etc.)

---

**🛡️ Lembre-se: A segurança está na configuração de cada projeto, não na biblioteca!**