> ## 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.

# Security

> How Driftless handles encryption, API keys, OAuth, and data protection.

## Encryption

All secrets stored in Driftless are encrypted with **AES-256-GCM** before they reach the database. This includes:

* API keys
* Webhook secrets
* GitHub App credentials
* Model provider keys (BYOM)
* OAuth tokens and authorization codes

The encryption key is derived from environment variables and never stored in the database.

<Warning>
  Never store plaintext secrets in Driftless. The encryption layer is mandatory and applied transparently.
</Warning>

## API keys

API keys are the primary authentication mechanism for the CLI and CI.

* Keys are generated with a `drift_` prefix for easy identification
* The raw key is shown **only once** at creation time
* Keys are stored as salted hashes; the raw value cannot be recovered
* Keys can be revoked at any time from the dashboard
* Multiple keys per workspace are supported

Create keys from the dashboard under **Settings > API Keys** or via the CLI:

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

## OAuth & MCP

Driftless supports OAuth 2.0 authorization for MCP (Model Context Protocol) client applications such as ChatGPT and Claude. OAuth allows third-party AI clients to access your workspace context with explicit user consent.

### OAuth scopes

| Scope           | Description                       |
| --------------- | --------------------------------- |
| `context:read`  | Read topics and context           |
| `topics:create` | Create new topics                 |
| `topics:write`  | Update existing topics            |
| `context:diff`  | Read topic diff for local changes |

### OAuth flow

1. The MCP client redirects the user to `/api/v1/oauth/authorize` on the Driftless API
2. The user consents in the dashboard at `/oauth/authorize`
3. The API issues an authorization code (PKCE-supported)
4. The client exchanges the code for an access token at `/api/v1/oauth/token`
5. The client uses the bearer token to call MCP tools

### Token security

* Authorization codes, access tokens, and refresh tokens are stored as hashes only, never plaintext
* Tokens are never logged or returned after initial issuance
* The MCP server (`apps/mcp`) is a protocol adapter that calls the existing Driftless REST API. It never accesses Postgres or internal libraries directly.

## Data handling

| Data          | Storage           | Encryption         |
| ------------- | ----------------- | ------------------ |
| Topic content | Postgres          | At rest (Supabase) |
| API keys      | Postgres (hashed) | Hashed + encrypted |
| GitHub tokens | Postgres          | AES-256-GCM        |
| OAuth tokens  | Postgres (hashed) | Hashed + encrypted |
| Source code   | Never stored      | N/A                |

Driftless **never stores** your source code. Only structural metadata from topics anchors (file patterns) and PR file lists are stored.

## GitHub App permissions

The GitHub App requests the minimum permissions required:

| Permission                       | Why                                    |
| -------------------------------- | -------------------------------------- |
| **Contents (read)**              | Fetch list of changed files per commit |
| **Pull requests (read & write)** | Post and update context comments       |
| **Issues (read & write)**        | PR comments use the Issues API         |
| **Metadata (read)**              | Required by GitHub for all apps        |

The app never clones repositories and never reads source file contents.

## Network

* All traffic between CLI, dashboard, and API is HTTPS
* API keys are sent in `x-api-key` headers, never in URL parameters
* Webhook payloads are verified with HMAC signatures
* The API runs on Render with encrypted environment variables

## Reporting

If you discover a security issue, please report it to [security@driftless.icu](mailto:security@driftless.icu). Do not open a public issue.