auth-yes/ONBOARDING.md

# Auth-Yes — Application Integration & Architecture Guide

Auth-Yes is a standalone, zero-trust Identity and Access Management (IAM) fabric
and WebAuthn Passkey authority. It provides microsecond session validation,
cryptographic workload identity, and decoupled application-level Role-Based
Access Control (RBAC).

This guide provides a universal, technology-agnostic architectural reference for
developers and system administrators integrating services into the Auth-Yes
ecosystem.

---

## 1. System Architecture & Defense-in-Depth Model

Auth-Yes implements a **three-tier defense model**, allowing applications to
choose the integration depth that best fits their architecture:

```
                [ Public Internet / User Browser ]
                                │
                  1. WebAuthn Passkey Login
                  2. Wildcard Cookie: *.yourdomain.org
                                │
                                ▼
            ═════════════════════════════════════════
            Ingress Reverse Proxy (Traefik, Nginx, etc.)
            ═════════════════════════════════════════
                                │
           ┌────────────────────┴────────────────────┐
           ▼                                         ▼
[ Tier 1 & 2: Edge ForwardAuth ]          [ Tier 3: Native Zero-Trust ]
(Off-the-shelf UIs / 3rd-Party)              (Microservices & APIs)
           │                                         │
           │ GET /api/forward-auth                   │ 1. Extract session token
           │ (Valkey Cache Lookup)                   │ 2. Query Workload API Socket
           │                                         ▼
           │                        ┌─────────────────────────────────┐
           │                        │ SPIRE Agent (Workload API)      │
           │                        │ - Issues X.509 SVID             │
           │                        │ - spiffe://<trust-domain>/<app> │
           │                        └────────────────┬────────────────┘
           │                                         │
           │                                         │ ConnectRPC over HTTP/2
           ▼                                         ▼
═════════════════════════════════════════════════════════════════════
Auth-Yes Central Gateway (auth-api:8000)
- Microsecond Session Validation (Valkey L1/L2 with RESP3 Tracking)
- Cryptographic Workload SVID Attestation (spire_ffi)
- Default-Deny PostgreSQL Application RBAC Grants (grants table)
═════════════════════════════════════════════════════════════════════
```

### The Three Integration Tiers:

| Tier                         | Target Use Case                                       | Integration Mechanism                       | Protocol / Transport                        | Code Required              |
| :--------------------------- | :---------------------------------------------------- | :------------------------------------------ | :------------------------------------------ | :------------------------- |
| **Tier 1: Global Edge**      | Pre-release & unmapped internal services              | Universal proxy perimeter fallback          | HTTP 302 Redirect to `/login`               | None                       |
| **Tier 2: Edge ForwardAuth** | Off-the-shelf apps, admin dashboards, legacy web UIs  | Reverse proxy ForwardAuth route             | HTTP `GET /api/forward-auth`                | None                       |
| **Tier 3: Zero-Trust RPC**   | Native microservices, custom APIs, streaming backends | Application SDK or direct ConnectRPC client | ConnectRPC / gRPC over HTTP/2 + SPIFFE mTLS | Minimal (Middleware / RPC) |

---

## 2. Core Identity & Authorization Primitives

### 2.1. User Session Identifiers

- **Browser Clients:** Auth-Yes issues an HTTP-only, secure session cookie
  (`session_id`) scoped to the parent domain (e.g., `.yourdomain.org`). Browsers
  automatically transmit this cookie across all subdomains.
- **API / Programmatic Clients:** Applications accept standard Bearer
  authorization headers: `Authorization: Bearer <session_token>`.

### 2.2. Workload Identity (SPIFFE / SPIRE)

- Microservices obtain cryptographic identities (X.509 SVIDs) by connecting to
  the local SPIRE Workload API UNIX domain socket at
  `/var/run/spire/agent.sock`.
- SVIDs follow the standard SPIFFE ID URI format:
  `spiffe://<trust-domain>/<workload-name>` (e.g.,
  `spiffe://system.local/payment-service`).
- When an application calls Auth-Yes, Auth-Yes extracts and attests the caller's
  SPIFFE ID to verify application authenticity.

### 2.3. Decoupled Default-Deny RBAC

Auth-Yes decouples **Authentication** (who the user is) from **Authorization**
(what application they are permitted to access):

1. **Default-Deny:** A valid user session has **zero application permissions by
   default**.
2. **Grant Evaluation:** When a service validates a session, Auth-Yes evaluates
   the internal grant matrix:
   ```sql
   SELECT role FROM grants WHERE user_id = $1 AND app_id = $2;
   ```
3. **Scope Payloads:** If a grant exists, Auth-Yes returns
   `{ valid: true, uuid: "...", scopes: ["<role>"] }`. If no grant exists, it
   returns `{ valid: false, error: "Validation failed" }` resulting in an
   immediate `403 Forbidden`.

---

## 3. Integration Patterns

### Pattern A: Edge ForwardAuth (Zero-Code / Reverse Proxy)

For off-the-shelf web applications (e.g., Grafana, Portainer, PgAdmin),
configure your ingress reverse proxy to query Auth-Yes before routing traffic to
the upstream container.

#### Traefik Example:

```yaml
# In Traefik dynamic configuration or container labels:
labels:
  - "traefik.http.routers.myapp.middlewares=auth-forward@docker"
  - "traefik.http.middlewares.auth-forward.forwardauth.address=http://auth-api:8000/api/forward-auth"
  - "traefik.http.middlewares.auth-forward.forwardauth.trustForwardHeader=true"
  - "traefik.http.middlewares.auth-forward.forwardauth.authResponseHeaders=X-Forwarded-User,X-Forwarded-User-Id"
```

- **Behavior:**
  - If valid: Auth-Yes returns HTTP `200 OK` and injects upstream identity
    headers (`X-Forwarded-User: <username>`, `X-Forwarded-User-Id: <uuid>`).
  - If missing / invalid: Auth-Yes returns HTTP `401 Unauthorized` or redirects
    unauthenticated browsers to `/login`.

---

### Pattern B: Native ConnectRPC / gRPC (Language-Agnostic)

For services written in Go, Rust, Python, Java, or C#, applications can
communicate directly with the Auth-Yes ConnectRPC endpoint over internal HTTP/2
multiplexing.

#### Protobuf Contract (`auth.proto`):

```protobuf
syntax = "proto3";
package auth.v1;

service AuthService {
  rpc ValidateSession (ValidateSessionRequest) returns (ValidateSessionResponse);
}

message ValidateSessionRequest {
  string token = 1;
}

message ValidateSessionResponse {
  bool valid = 1;
  string uuid = 2;
  repeated string scopes = 3;
  string error = 4;
}
```

- **Endpoint:** `http://auth-api:8000/auth.v1.AuthService/ValidateSession` (or
  internal mesh DNS).
- **Workload Identity:** Pass client TLS certificates fetched from the SPIRE
  Workload API socket to enable mTLS attestation.

---

### Pattern C: TypeScript & Deno Applications (`@auth-yes/sdk`)

For TypeScript/JavaScript runtimes, `@auth-yes/sdk` provides a zero-dependency
client with built-in **RESP3 client-side cache tracking** (L1 memory cache
invalidated in real time via Valkey broadcast events).

#### 1. Import Reference:

```json
{
  "imports": {
    "@auth-yes/sdk": "https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts",
    "@auth-yes/sdk/hono": "https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/hono.ts"
  }
}
```

#### 2. Service Integration:

```typescript
import { createAuthSdk } from "@auth-yes/sdk";

// Initialize SDK with internal mesh endpoints
const authSdk = createAuthSdk({
  authApiUrl: Deno.env.get("AUTH_API_URL") || "http://auth-api:8000",
  valkeyUrl: Deno.env.get("VALKEY_URL"), // Optional: Enables real-time L1 cache tracking
});

// Validate any session token (cookie or header)
const result = await authSdk.validateSession(sessionToken);

if (result.valid) {
  console.log(`User Authenticated: ${result.uuid}, Roles:`, result.scopes);
} else {
  console.warn(`Access Denied: ${result.error}`);
}
```

---

## 4. Container & Infrastructure Topology

To connect any application container to Auth-Yes and SPIRE, ensure two
infrastructure prerequisites:

1. **Network Mesh:** Attach the container to the internal bridge network
   (`auth-internal-net`) and ingress proxy network (`traefik-net`).
2. **Workload Socket:** Mount the pre-existing named volume `spire-socket` as
   read-only (`:ro`).

### Generic Compose Template:

```yaml
version: "3.8"

services:
  my-service:
    image: ${REG}/library/my-service:latest
    container_name: my-service
    environment:
      - AUTH_API_URL=http://auth-api:8000
      - VALKEY_URL=redis://auth-valkey:6379
      - SPIFFE_ENDPOINT_SOCKET=/var/run/spire/agent.sock
    networks:
      - default # auth-internal-net
      - traefik-net # Ingress proxy
    volumes:
      # Read-only SPIRE Workload API UNIX domain socket
      - spire-socket:/var/run/spire:ro

volumes:
  spire-socket:
    external: true

networks:
  default:
    name: auth-internal-net
    external: true
  traefik-net:
    external: true
```

---

## 5. Administrative Lifecycle & Access Provisioning

Administrative operations are managed via the **Auth-Yes Admin Console**
(`https://auth.<domain>/admin`):

### 5.1. Application Registration (`/admin/apps`)

Every internal service connecting to Auth-Yes must be registered:

- **Application Name:** Human-readable label (e.g., `Analytics Engine`).
- **SPIFFE ID:** Cryptographic workload URI matching the service's container
  attestation (e.g., `spiffe://system.local/analytics-engine`).
- **Description:** Functional description of the application.

### 5.2. User Onboarding & Invite Token Taxonomy (`/admin/invites`)

Auth-Yes uses a structured invite token model for user registration:

1. **Site-Scoped Token (Recommended for subsidiary applications):**
   - Pre-binds an invite code to a specific application and role (`user`,
     `operator`, `admin`).
   - When a user registers their passkey using this token, their account is
     automatically activated and granted immediate access to the designated
     application.
2. **Global Admin Token:**
   - Grants system-wide administrative access across Auth-Yes management views.
3. **Open / Pending Token:**
   - Creates an account in `pending` state requiring explicit administrator
     review and role assignment before login is permitted.

### 5.3. Dynamic Role Assignment & Instant Revocation (`/admin/users/:id`)

- **Grant Management:** Administrators can attach or adjust application roles
  directly in the user profile matrix.
- **Instant Session Revocation:** Terminating a session or revoking an
  application grant purges active tokens from Valkey in $< 1$ millisecond,
  immediately blocking subsequent requests across all microservices.

---

## 6. Verification & Troubleshooting

| Check                               | Verification Command / Procedure                               | Expected Diagnostic                                                    |
| :---------------------------------- | :------------------------------------------------------------- | :--------------------------------------------------------------------- |
| **1. Workload Socket Availability** | `ls -la /var/run/spire/agent.sock` inside container            | File exists with type `s` (UNIX domain socket).                        |
| **2. Auth Mesh Connectivity**       | `curl -I http://auth-api:8000/health` inside container         | Returns HTTP `200 OK`.                                                 |
| **3. Unregistered Service Check**   | Calling `ValidateSession` from an unassigned application       | Returns HTTP `403 Forbidden: Validation failed`.                       |
| **4. Grant Authorization Check**    | Calling `ValidateSession` with an active user grant            | Returns `{ valid: true, uuid: "...", scopes: ["..."] }`.               |
| **5. Revocation Propagation**       | Revoke session in Admin Console $\rightarrow$ Re-issue request | Instant transition to HTTP `401 Unauthorized` without server restarts. |