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

# SPIRE

> SPIFFE Runtime Environment — the identity backbone that issues X.509 SVIDs and JWT-SVIDs to every agent process.

## What It Does

SPIRE (SPIFFE Runtime Environment) is the **identity foundation** of Hexr. It issues cryptographic identities to every agent process using the SPIFFE standard.

***

## Components

| Component          | Role                                       | Runs As                          |
| ------------------ | ------------------------------------------ | -------------------------------- |
| **SPIRE Server**   | Certificate authority, registration store  | StatefulSet in `spire` namespace |
| **SPIRE Agent**    | Node-level attestor, workload API provider | DaemonSet (every node)           |
| **OIDC Discovery** | Publishes JWKS for cloud federation        | Deployment at `oidc.hexr.cloud`  |

***

## Identity Issuance Flow

<Steps>
  <Step title="Process starts in agent pod">
    A new process spawns (e.g., PID 42 with role `researcher`). The PID Mapper detects it.
  </Step>

  <Step title="PID Mapper requests SVID">
    PID Mapper calls the SPIRE Agent's Workload API (`FetchX509SVID`) with the process selectors.
  </Step>

  <Step title="SPIRE Agent performs attestation">
    The agent verifies workload identity using Kubernetes selectors: `k8s:pod-uid`, `k8s:ns`, `hexr:role`.
  </Step>

  <Step title="SPIRE Server signs certificate">
    The server matches the request against registration entries and signs an X.509 SVID for `spiffe://.../{role}`.
  </Step>

  <Step title="SVID delivered to pod">
    The signed X.509 SVID (5-minute TTL) is delivered back to the pod via the Workload API. The process now has a cryptographic identity.
  </Step>
</Steps>

```
Agent Pod → PID Mapper → SPIRE Agent (attestation) → SPIRE Server (sign cert) → X.509 SVID → Pod
```

***

## SPIFFE ID Format

```
spiffe://{trust-domain}/agent/{tenant}/{agent-name}/{role}
```

Examples:

```
spiffe://hexr.cloud/agent/acme-corp/research-analyst/main
spiffe://hexr.cloud/agent/acme-corp/content-crew/researcher
spiffe://hexr.cloud/agent/acme-corp/content-crew/writer
spiffe://demo.hexr.dev/agent/dev-team/my-agent/main
```

***

## Trust Domains

| Domain          | Environment                       |
| --------------- | --------------------------------- |
| `hexr.cloud`    | Production (Hexr Cloud)           |
| `demo.hexr.dev` | Development / self-hosted default |
| Custom          | Configurable per deployment       |

***

## OIDC Discovery

SPIRE publishes a JWKS endpoint at `oidc.hexr.cloud/.well-known/openid-configuration`, enabling cloud providers to validate JWT-SVIDs for credential exchange:

```
https://oidc.hexr.cloud/.well-known/openid-configuration
https://oidc.hexr.cloud/keys
```

This is how `hexr_tool()` credential exchange works — cloud providers trust the SPIRE OIDC endpoint as an identity provider.

***

## Helm Values

Key SPIRE configuration in Helm `values-saas.yaml`:

```yaml theme={null}
spire:
  server:
    trustDomain: hexr.cloud
    ca:
      ttl: 24h
    registration:
      enabled: true
  agent:
    socketPath: /run/spire/sockets/agent.sock
  oidc:
    enabled: true
    hostname: oidc.hexr.cloud
```