> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Seguridad

> Cómo Driftless maneja el cifrado, las API keys, OAuth y la protección de datos.

## Cifrado

Todos los secretos almacenados en Driftless se cifran con **AES-256-GCM** antes de llegar a la base de datos. Esto incluye:

* API keys
* Secretos de webhooks
* Credenciales de la GitHub App
* Keys de proveedores de modelos (BYOM)
* Tokens OAuth y códigos de autorización

La clave de cifrado se deriva de variables de entorno y nunca se almacena en la base de datos.

<Warning>
  Nunca almacenes secretos en texto plano en Driftless. La capa de cifrado es obligatoria y se aplica de forma transparente.
</Warning>

## API keys

Las API keys son el mecanismo de autenticación principal para la CLI y CI.

* Las keys se generan con un prefijo `drift_` para identificarlas fácilmente
* La key en crudo se muestra **solo una vez**, al momento de crearla
* Las keys se almacenan como hashes con salt; el valor en crudo no se puede recuperar
* Las keys se pueden revocar en cualquier momento desde el dashboard
* Se admiten múltiples keys por workspace

Crea keys desde el dashboard en **Settings > API Keys** o mediante la CLI:

```bash theme={"theme":"github-light"}
driftless login
```

## OAuth y MCP

Driftless admite autorización OAuth 2.0 para aplicaciones cliente de MCP (Model Context Protocol) como ChatGPT y Claude. OAuth permite que clientes de IA de terceros accedan al contexto de tu workspace con el consentimiento explícito del usuario.

### Scopes de OAuth

| Scope           | Descripción                                |
| --------------- | ------------------------------------------ |
| `context:read`  | Lee topics y contexto                      |
| `topics:create` | Crea nuevos topics                         |
| `topics:write`  | Actualiza topics existentes                |
| `context:diff`  | Lee el diff de topics para cambios locales |

### Flujo de OAuth

1. El cliente MCP redirige al usuario a `/api/v1/oauth/authorize` en la API de Driftless
2. El usuario da su consentimiento en el dashboard en `/oauth/authorize`
3. La API emite un código de autorización (con soporte PKCE)
4. El cliente intercambia el código por un token de acceso en `/api/v1/oauth/token`
5. El cliente usa el token bearer para llamar a las herramientas MCP

### Seguridad de los tokens

* Los códigos de autorización, tokens de acceso y tokens de refresco se almacenan solo como hashes, nunca en texto plano
* Los tokens nunca se registran ni se devuelven después de la emisión inicial
* El servidor MCP (`apps/mcp`) es un adaptador de protocolo que llama a la API REST existente de Driftless. Nunca accede a Postgres ni a librerías internas directamente.

## Manejo de datos

| Dato                | Almacenamiento      | Cifrado              |
| ------------------- | ------------------- | -------------------- |
| Contenido de topics | Postgres            | En reposo (Supabase) |
| API keys            | Postgres (hasheado) | Hasheado + cifrado   |
| Tokens de GitHub    | Postgres            | AES-256-GCM          |
| Tokens OAuth        | Postgres (hasheado) | Hasheado + cifrado   |
| Código fuente       | Nunca se almacena   | N/A                  |

Driftless **nunca almacena** tu código fuente. Solo se almacenan metadatos estructurales de los anclajes de topics (patrones de archivos) y las listas de archivos de los PRs.

## Permisos de la GitHub App

La GitHub App solicita los permisos mínimos requeridos:

| Permiso                          | Por qué                                           |
| -------------------------------- | ------------------------------------------------- |
| **Contents (read)**              | Obtiene la lista de archivos cambiados por commit |
| **Pull requests (read & write)** | Publica y actualiza comentarios de contexto       |
| **Issues (read & write)**        | Los comentarios de PR usan la API de Issues       |
| **Metadata (read)**              | Requerido por GitHub para todas las apps          |

La app nunca clona repositorios y nunca lee el contenido de los archivos fuente.

## Red

* Todo el tráfico entre la CLI, el dashboard y la API es HTTPS
* Las API keys se envían en cabeceras `x-api-key`, nunca en parámetros de URL
* Las cargas de webhooks se verifican con firmas HMAC
* La API corre en Render con variables de entorno cifradas

## Reportes

Si descubres un problema de seguridad, por favor repórtalo a [security@driftless.icu](mailto:security@driftless.icu). No abras un issue público.