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

# Security Reference

> Technical security controls for publishable keys, token validation, and runtime isolation

This page describes implemented security controls in the current auth model.

## Ticket exchange security (`/api/auth/pk-ticket`)

1. Validate `publishable_key` format
2. Hash key and look up active key record
3. Resolve org context from key
4. Enforce per-key `allowed_origins` (required, no org-level fallback)
5. If `id_token` provided: validate signature/issuer/audience using org IDP config
6. Issue short-lived ticket with org + user identity

## Publishable key controls

| Control             | Behavior                                                           |
| ------------------- | ------------------------------------------------------------------ |
| Stored format       | SHA-256 hash (`key_hash`), never plaintext                         |
| Display format      | Prefix only (`key_prefix`) in UI                                   |
| Revocation          | Immediate via `revoked_at`                                         |
| Origin restrictions | Per-key `allowed_origins` (required on every key, no org fallback) |
| Usage tracking      | Best-effort `last_used_at` updates                                 |

## Token validation controls

| Claim | Validation                                |
| ----- | ----------------------------------------- |
| `iss` | Must match configured issuer/domain       |
| `sub` | Required for identity mapping             |
| `aud` | Must match configured allowed audience(s) |
| `exp` | Must be valid at verification time        |

Algorithms are limited to asymmetric signatures (no `none`, no shared-secret algorithm bypasses).

## Runtime isolation

| Component        | Isolation boundary                            |
| ---------------- | --------------------------------------------- |
| ThreadManager DO | User/org scoped metadata and connection state |
| ThreadAgent DO   | Thread-scoped execution state                 |
| Tool routing     | Routed to connection that registered the tool |

## Recommended operational practices

* Scope keys by environment (dev/staging/prod)
* Restrict key origins tightly
* Revoke keys during incident response
* Keep IDP issuer/audience config in sync with auth provider
* Monitor auth failures (`INVALID_KEY`, origin failures, token failures)

<CardGroup cols={2}>
  <Card title="Identity Providers" icon="shield" href="/identity-providers/index" />

  <Card title="Authentication" icon="key" href="/authentication" />
</CardGroup>