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

# SPIFFE Identity

> Every agent process gets a unique cryptographic identity — here's how SPIFFE and SPIRE make it work.

## What Is SPIFFE?

**SPIFFE** (Secure Production Identity Framework for Everyone) is a set of open standards for service identity. A SPIFFE ID is a URI that uniquely identifies a workload.

**SPIFFE ID structure:**

| Part         | Example            | Description                             |
| ------------ | ------------------ | --------------------------------------- |
| Trust domain | `hexr.cloud`       | Your SPIRE trust domain                 |
| Type         | `agent`            | Workload type (always `agent` for Hexr) |
| Tenant       | `acme-corp`        | Tenant namespace                        |
| Agent name   | `research-analyst` | From `@hexr_agent(name=...)`            |
| Role         | `researcher`       | Sub-agent process role                  |

**Full example:**

```
spiffe://hexr.cloud/agent/acme-corp/research-analyst/researcher
```

## What Is an SVID?

An **SVID** (SPIFFE Verifiable Identity Document) is the cryptographic proof of a SPIFFE ID. Hexr uses two types:

| Type           | Format                          | Used For                         |
| -------------- | ------------------------------- | -------------------------------- |
| **X.509 SVID** | X.509 certificate + private key | mTLS between services            |
| **JWT-SVID**   | Signed JWT token                | Cloud credential exchange (OIDC) |

***

## Per-Process Identity

Hexr's key innovation is assigning a unique SPIFFE ID to each **process** within an agent container — not just the pod:

```
Pod: content-crew (tenant: acme-corp)
├── PID 1 (main)       → spiffe://hexr.cloud/agent/acme-corp/content-crew/main
├── PID 42 (researcher) → spiffe://hexr.cloud/agent/acme-corp/content-crew/researcher
├── PID 43 (writer)     → spiffe://hexr.cloud/agent/acme-corp/content-crew/writer
└── PID 44 (editor)     → spiffe://hexr.cloud/agent/acme-corp/content-crew/editor
```

This enables:

* **Per-role cloud access** — the researcher can access BigQuery but not S3
* **Per-role cost tracking** — attribute LLM costs to each role
* **Per-role audit logs** — know exactly which sub-agent did what

***

## Lifecycle

The complete lifecycle of a SPIFFE identity — from build to cloud access:

<Steps>
  <Step title="Build: AST Discovery" icon="magnifying-glass">
    `hexr build` scans your Python source via AST analysis. Discovers all agent roles
    (researcher, writer, editor) and generates process context JSON files.
  </Step>

  <Step title="Pod starts: SDK installed" icon="download">
    Init container installs the Hexr SDK from private PyPI into a shared volume.
  </Step>

  <Step title="PID Mapper: Process registration" icon="fingerprint">
    When the agent process starts (e.g., "researcher", PID 42), the PID Mapper reads `/proc`,
    maps the container PID to the host PID, and writes enriched context JSON.
  </Step>

  <Step title="SPIRE: SVID issued" icon="certificate">
    The Auto-Registrar creates a SPIRE entry. SPIRE issues an **X.509-SVID** with a 5-minute
    TTL (auto-renewed at 50% TTL). The SVID contains the per-process SPIFFE ID.
  </Step>

  <Step title="Runtime: mTLS + cloud access" icon="shield-check">
    The agent uses its SVID for mTLS (via Envoy) and presents its JWT-SVID to cloud
    providers (AWS STS, GCP WIF, Azure) for temporary credential exchange.
  </Step>
</Steps>

***

## Trust Domain

| Deployment            | Trust Domain          |
| --------------------- | --------------------- |
| Hexr Cloud            | `hexr.cloud`          |
| Self-hosted (default) | `demo.hexr.dev`       |
| Custom                | Configurable via Helm |

***

## Certificate Rotation

SVIDs are short-lived and auto-rotated:

| Certificate    | TTL       | Rotation                           |
| -------------- | --------- | ---------------------------------- |
| X.509 SVID     | 5 minutes | SPIRE auto-renews at 50% TTL       |
| JWT-SVID       | 5 minutes | Issued on-demand for STS exchange  |
| CA certificate | 24 hours  | SPIRE Server rotates automatically |