# Como Funciona a Autenticacao do TecJustica MCP

Este documento explica de forma simples como funciona o sistema de autenticacao que protege o servidor MCP.

---

## 1. O Problema

### Situacao anterior
```
Usuario ──────────────────────────────────────────────────> MCP Server
         "Quero ver meus processos"                         "Quem e voce??"
                                                            Sem identificacao
```

O Claude (ou qualquer cliente) podia acessar o servidor MCP, mas nao sabiamos **quem** estava acessando. Isso e perigoso porque:
- Qualquer pessoa poderia ver os processos de qualquer outra
- Nao temos como aplicar permissoes (quem pode ver o que)
- Nao temos como auditar acessos

### Situacao com autenticacao
```
Usuario ──── Login ────> Supabase ──── Token ────> MCP Server
         "Sou marco@email.com"     "Aqui esta seu     "Ah, e o Marco!
          senha: ***"               cracha digital"    Pode ver seus
                                                       processos."
                                                       Identificado
```

---

## 2. Analogia: O Hotel

Pense no sistema como um **hotel**:

| Elemento | No Hotel | No Sistema |
|----------|----------|------------|
| **Voce** | Hospede | Usuario do TecJustica |
| **Recepcao** | Onde voce faz check-in | Supabase Auth (login) |
| **Cartao do quarto** | Abre so o seu quarto | Token JWT (acesso aos seus dados) |
| **Quarto** | Seu espaco privado | Seus processos no banco |
| **Concierge** | Servicos do hotel | MCP Server (Claude) |

### Fluxo do Hotel:
1. Voce chega no hotel (abre o Claude)
2. Vai na recepcao fazer check-in (faz login no Supabase)
3. Mostra documento e recebe cartao do quarto (recebe Token)
4. Pede ao concierge para trazer algo do quarto (pede ao Claude para buscar processo)
5. Concierge usa seu cartao para acessar so o seu quarto (MCP usa token para acessar so seus dados)

---

## 3. Glossario - Termos Tecnicos

### OAuth 2.1
**O que e:** Um protocolo (conjunto de regras) para autorizacao segura.

**Analogia:** E como o sistema padronizado de cartoes de hotel. Todos os hoteis usam o mesmo tipo de cartao magnetico, entao voce ja sabe como funciona.

**Por que usamos:** Porque e o padrao da industria. Claude, Google, Facebook - todos usam OAuth.

---

### Token JWT
**O que e:** Um "cracha digital" que contem informacoes sobre voce.

**Formato:** E uma string longa que parece isso:
```
eyJhbGciOiJFUzI1NiIs...
```

**O que tem dentro:**
```json
{
  "sub": "uuid-do-usuario",      // Quem e voce
  "email": "marco@email.com",    // Seu email
  "exp": 1735819200,             // Quando expira
  "aud": "authenticated"         // Para quem e valido
}
```

**Analogia:** E como um cracha de empresa que tem sua foto, nome, cargo e data de validade.

---

### SupabaseProvider
**O que e:** O componente do FastMCP que conecta nosso servidor MCP ao Supabase Auth.

**Por que precisamos:** O Claude fala "OAuth". O Supabase fala "OAuth". O SupabaseProvider faz a integracao entre os dois automaticamente — registro de clientes, login, troca de tokens.

**Analogia:** E como um concierge que fala varios idiomas e organiza tudo automaticamente.

---

### DualTokenVerifier
**O que e:** O "porteiro" do MCP Server que aceita dois tipos de credencial.

**Dois tipos de cracha:**
1. **JWT do Supabase** — Token do login normal (via OAuth)
2. **API Key** (`tk_...`) — Chave fixa para acesso programatico

**Analogia:**
- JWT = Cartao do hotel (expira, precisa renovar)
- API Key = Chave mestra do funcionario (nao expira, acesso direto)

---

### JWKS (JSON Web Key Set)
**O que e:** Um conjunto de chaves publicas que o Supabase publica para que qualquer um possa verificar se um token e autentico.

**Como funciona:** O Supabase assina tokens com uma chave privada (secreta). Publica a chave publica no JWKS. Nosso servidor usa essa chave publica para verificar: "esse token foi realmente assinado pelo Supabase?"

**Analogia:** E como verificar a marca d'agua de uma nota de dinheiro — qualquer um pode verificar, mas so o Banco Central pode criar.

---

## 4. Fluxo Completo - Passo a Passo

```
     USUARIO              CLAUDE              MCP SERVER           SUPABASE
        |                    |                    |                    |
        |                    |                    |                    |
   ┌────┴────┐               |                    |                    |
   | 1. Abre |               |                    |                    |
   |  Claude |               |                    |                    |
   └────┬────┘               |                    |                    |
        |                    |                    |                    |
        |  "Adiciona MCP"    |                    |                    |
        |───────────────────>|                    |                    |
        |                    |                    |                    |
        |                    |  2. Discovery      |                    |
        |                    |───────────────────>|                    |
        |                    |                    |                    |
        |                    |  3. Registro (DCR) |                    |
        |                    |───────────────────>| ──── delega ────> |
        |                    |                    |                    |
        |  4. Abre janela    |                    |                    |
        |     de login       |                    |                    |
        |<───────────────────|                    |                    |
        |                    |                    |                    |
   ┌────┴────┐               |                    |                    |
   | 5. Faz  |               |                    |                    |
   |  login  |───────────────────────────────────────────────────────>|
   └────┬────┘               |                    |                    |
        |                    |                    |                    |
        |                    |               6. Token exchange        |
        |                    |               (automatico)             |
        |                    |                    |<────── JWT ──────|
        |                    |                    |                    |
        |  7. "Conectado!"   |                    |                    |
        |<───────────────────|                    |                    |
        |                    |                    |                    |
   ┌────┴────┐               |                    |                    |
   | 8."Liste|               |                    |                    |
   | meus    |               |  9. "Liste processos                   |
   |processos"──────────────>|      do usuario X"  |                   |
   └────┬────┘               |───────────────────>|                    |
        |                    |                    |                    |
        |                    |                    | 10. Valida JWT     |
        |                    |                    | via JWKS (ES256)   |
        |                    |                    |                    |
        |                    | 11. "Processos     |                    |
        |  12. Mostra        |     do Marco"      |                    |
        |      processos     |<───────────────────|                    |
        |<───────────────────|                    |                    |
        |                    |                    |                    |
```

---

## 5. O Que Cada Componente Faz

### Supabase (O Guardiao das Identidades)
```
┌─────────────────────────────────────────────────────────┐
│                      SUPABASE                            │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Banco de Usuarios                                      │
│     - Guarda emails, senhas (criptografadas)            │
│     - Sabe quem e quem                                  │
│                                                          │
│  OAuth Server                                           │
│     - Faz login dos usuarios                            │
│     - Gera tokens JWT (assinados com ES256)             │
│     - Publica chaves publicas no JWKS                   │
│     - Gerencia consent automaticamente                  │
│                                                          │
│  DCR (Dynamic Client Registration)                      │
│     - Registra automaticamente clientes MCP             │
│     - Nao precisa de client_id/secret manuais           │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

### MCP Server (O Servidor de Dados)
```
┌─────────────────────────────────────────────────────────┐
│                     MCP SERVER                           │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  SupabaseProvider (Organizador)                         │
│     - Gerencia discovery, DCR, authorize, token         │
│     - Delega tudo ao Supabase automaticamente           │
│                                                          │
│  DualTokenVerifier (Porteiro)                           │
│     - Aceita JWT Supabase (valida via JWKS)             │
│     - Aceita API Keys tk_ (valida via hash SHA-256)     │
│                                                          │
│  Tools (13 Ferramentas)                                 │
│     - listar_processos(), visao_geral_processo()        │
│     - grep_documentos(), analisar(), etc.               │
│     - So funcionam se token for valido                  │
│                                                          │
│  Conexao com Banco                                      │
│     - Busca dados no Supabase                           │
│     - Usa o user_id do token para filtrar (RLS)         │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

---

## 6. O Codigo Explicado

### No MCP Server (`server.py`)

```python
from fastmcp import FastMCP
from fastmcp.server.auth.providers.supabase import SupabaseProvider
from fastmcp.server.auth.providers.jwt import JWTVerifier

# JWTVerifier com ES256 — valida tokens via JWKS (chaves publicas)
jwt_verifier = JWTVerifier(
    jwks_uri=f"{supabase_url}/auth/v1/.well-known/jwks.json",
    issuer=f"{supabase_url}/auth/v1",
    algorithm="ES256",
)

# DualTokenVerifier — aceita JWT Supabase OU API Keys tk_
dual_verifier = DualTokenVerifier(jwt_verifier)

# SupabaseProvider — gerencia todo o fluxo OAuth automaticamente
auth = SupabaseProvider(
    project_url=supabase_url,
    base_url="https://mcp.tecjustica.com",
    token_verifier=dual_verifier,
)

mcp = FastMCP(name="TecJustica MCP Server", version="4.0.0", auth=auth)
```

**O que cada parte faz:**

| Componente | O que faz |
|------------|-----------|
| `JWTVerifier` | Verifica se o token JWT foi assinado pelo Supabase (via JWKS) |
| `DualTokenVerifier` | Aceita JWT ou API Key — decide qual validacao usar |
| `SupabaseProvider` | Organiza todo o fluxo OAuth (discovery, DCR, token exchange) |
| `auth=auth` | "Use esse sistema para verificar todos que entram" |

---

## 7. Seguranca - Por Que Isso E Seguro?

### 1. Senha nunca sai do Supabase
```
ERRADO:  Usuario -> Senha -> MCP Server -> Supabase
CERTO:   Usuario -> Senha -> Supabase (direto)
                              |
                           Token -> MCP Server
```

### 2. Validacao com chaves publicas (ES256)
```
Supabase assina token com chave PRIVADA (secreta)
MCP Server verifica com chave PUBLICA (aberta)
-> Servidor nunca precisa da chave privada
-> Chaves podem ser rotacionadas automaticamente
```

### 3. Token tem prazo de validade
```
Token gerado: 16:00
Token expira: 17:00 (1 hora depois)

As 17:01: "Token expirado, faca login novamente"
```

### 4. Token so funciona para quem foi gerado
```
Token do Marco nao funciona para a Ana.
Mesmo que alguem roube o token, so ve os dados do Marco.
```

### 5. HTTPS em tudo
```
Todas as comunicacoes sao criptografadas.
Mesmo que alguem intercepte, so ve dados embaralhados.
```

---

## 8. Dois Caminhos de Autenticacao

```
┌────────────────────────────────────────────────────────────┐
│                                                             │
│   Caminho 1: OAuth (via Claude Web)                        │
│   ─────────────────────────────────                        │
│   Usuario -> Claude -> Login Supabase -> JWT -> MCP        │
│   (automatico, transparente para o usuario)                │
│                                                             │
│   Caminho 2: API Key (via curl/scripts)                    │
│   ─────────────────────────────────────                    │
│   Developer -> tk_xxx... -> MCP                            │
│   (direto, sem OAuth, para automacao)                      │
│                                                             │
│   Caminho 3: Token Supabase direto (via curl)              │
│   ───────────────────────────────────────                  │
│   Developer -> email/senha -> Supabase -> JWT -> MCP       │
│   (para testes manuais)                                    │
│                                                             │
└────────────────────────────────────────────────────────────┘
```

---

## Duvidas Frequentes

**P: O usuario precisa fazer login toda vez?**
R: Nao. O token dura 1 hora. Depois, e renovado automaticamente (refresh token).

**P: Preciso de uma pagina de consent separada?**
R: Nao mais. O SupabaseProvider com DCR gerencia o consent automaticamente no Supabase.

**P: Por que nao usar so usuario/senha direto?**
R: Porque o Claude nunca deveria saber sua senha. OAuth garante que so o Supabase ve a senha.

**P: O que e PKCE?**
R: Protecao extra contra interceptacao. O Claude gera um codigo secreto antes de pedir login, e so quem tem esse codigo consegue o token final.

**P: E se alguem roubar a API Key?**
R: Pode acessar os dados do usuario associado. Por isso API Keys devem ser mantidas em segredo e podem ser revogadas trocando o hash na env var.

---

## Arquivos Relacionados

| Arquivo | O que faz |
|---------|-----------|
| `server.py` | Configura SupabaseProvider + DualTokenVerifier |
| `server.py:DualTokenVerifier` | Valida JWT ou API Key |
| `docs/OAUTH_FLOW.md` | Fluxo tecnico detalhado |

---

*Documento atualizado para TecJustica MCP v4.0.0 (marco/2025)*
