> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybrein.com/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
* 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
* A key stops working when its creator is removed from that workspace

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 |
| OAuth tokens  | Postgres (hashed) | Hashed + encrypted |
| Source code   | Never stored      | N/A                |

Driftless **never stores** your source code. Topics keep only the explicit paths and glob anchors that your team records.

## Network

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

## Protection against bulk extraction

Anything an authorized person can see in a browser can ultimately be copied.
Driftless therefore protects the enforceable boundary instead of claiming that
browser endpoints are secret:

* market-intelligence requests are limited per verified person and workspace,
  across all endpoints and source IPs;
* successful deliveries also have a database-backed hourly ceiling that
  survives deploys and multiple API instances;
* plan allowances and server-owned page sizes limit the amount delivered;
* record links and cursors are authenticated opaque values, while internal
  record ids are not exposed;
* authenticated responses are non-cacheable and the dashboard does not persist
  response bodies in browser storage.

## Reporting

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