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

# Authentication

> OIDC-compliant security layer with dual-layer in-memory caching.

The service implements a configurable, **OIDC-compliant security layer** designed for Zero-Trust environments.

## Operational modes

Authentication is treated as a toggleable effect. The mode is determined strictly by the `AUTH_TYPE` environment variable.

> **Strict Mode**
>
> `auth0` · `keycloak` · `custom`
>
> The service acts as a gatekeeper. All protected endpoints require a valid `Bearer` token in the `Authorization` header.

> **Guest Mode**
>
> `noop`
>
> The security layer defaults to a no-op provider, permitting all requests without validation. All authentication checks are skipped.

## Performance and caching

To maintain sub-millisecond overhead, the validation logic avoids synchronous round-trips to the Identity Provider on every request. Instead, it uses a **dual-layer in-memory strategy**.

> **L1 — Session cache**
>
> Once a JWT is cryptographically verified, its valid state is cached until the token's natural expiration (`exp` claim). Subsequent requests with the same token **bypass signature verification entirely**.

> **L2 — JWKS cache**
>
> Public keys (JSON Web Key Set) needed for verification are cached long-term and refreshed only if a token references an unknown Key ID (`kid`) — handling key rotation automatically.

## Request flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Gatekeeper
    participant L1 as L1 Cache<br/>(JWT, Sessions)
    participant L2 as L2 Cache<br/>(JWKS)
    participant IdP as Identity Provider

    Client->>Gatekeeper: HTTP GET (Bearer Token)

    Note right of Gatekeeper: Layer 1: Session Check
    Gatekeeper->>L1: Get(Token)

    alt Cache Hit (Fast Path)
        L1-->>Gatekeeper: Valid Session
    else Cache Miss (Slow Path)
        Note right of Gatekeeper: Layer 2: Key Lookup
        Gatekeeper->>Gatekeeper: Verify Header
        Gatekeeper->>L2: GetKey(kid)

        opt Key Missing (Rotation)
            L2->>IdP: Fetch JWKS
            IdP-->>L2: Public Keys
        end

        L2-->>Gatekeeper: Public Key
        Gatekeeper->>Gatekeeper: Verify Signature & Claims
        Gatekeeper->>L1: Put(Token, Session, TTL=exp)
        L1-->>Gatekeeper: Valid Session
    end

    Gatekeeper-->>Client: 200 OK
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.