# Auth-Yes — Practical Playbook & High-ROI Use Cases

**Classification:** System Operations & Integration Guide\
**Purpose:** Realistic, practical assessment of day-to-day effort across common
deployment, integration, and administrative scenarios.\
**Maintained By:** Auth-Yes IAM Architecture Team\
**Date:** August 2026

---

## Executive Overview

Auth-Yes is engineered to eliminate the operational friction of legacy IAM
systems (e.g. Keycloak, Okta, Auth0) while delivering mathematical zero-trust
guarantees. Below is a comprehensive assessment of the **11 core high-ROI
operational and integration scenarios**.

```
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                  EFFORT & COMPLEXITY MATRIX                                      │
├────┬─────────────────────────────────────────────────┬──────────────────┬────────────────────────┤
│ #  │ Scenario / Use Case                             │ Difficulty Level │ Time / Code Required   │
├────┼─────────────────────────────────────────────────┼──────────────────┼────────────────────────┤
│ 1  │ Appliance Setup & Cold Boot                     │ Low (Zero-Touch) │ 1 Command / < 2 min    │
│ 2  │ Tier 1 Ingress Auth (Grafana, Portainer, etc.)  │ Minimal          │ 3 Traefik Docker labels│
│ 3  │ Tier 2 Custom Web/SSR Apps (ed-droid, Next.js)  │ Minimal          │ 2 Lines of Code        │
│ 4  │ Headless Edge Daemons & IoT (RFC 9421 Sigs)     │ Low              │ HTTP Signature Headers │
│ 5  │ Internal Workload Mesh (mTLS & SPIFFE FFI)      │ Minimal          │ Auto-injected SVIDs    │
│ 6  │ Live Telemetry & WebSockets (Ghost Cockpit)     │ Minimal          │ 1 Middleware Guard     │
│ 7  │ Lost Device Recovery (2-of-3 SSS / BIP-39)      │ Zero Admin Toil  │ Self-Service UI        │
│ 8  │ Incident Response & Fleet-Wide Revocation       │ Low              │ 1-Click / < 30µs Mesh  │
│ 9  │ Multi-App RBAC & Scope Provisioning             │ Low              │ Simple Web UI Form     │
│ 10 │ Cryptographic Compliance & Audit Verification   │ Zero             │ Automated Merkle Logs  │
│ 11 │ Ephemeral Guest Sandboxes & Open Trial Access   │ Minimal          │ 1-Click / Zero Passkey │
└────┴─────────────────────────────────────────────────┴──────────────────┴────────────────────────┘
```

---

### Use Case 1: Setting Up the Auth System from Scratch

- **Difficulty Level:** **Low (Near Zero-Touch / < 2 Minutes)**
- **What you actually have to do:**
  1. Run `deno task setup` (generates `infra/stack.env` with cryptographically
     secure random secrets).
  2. Run `docker compose -f infra/compose.yml up -d`.
  3. Navigate to `https://auth.atyg.org/register` in your browser and register
     your first WebAuthn passkey (touch your YubiKey / Touch ID).
- **Why it's painless:**
  - The database schema (`users`, `apps`, `grants`, `passkeys`, `audit_ledger`)
    auto-migrates idempotently on first boot.
  - The first registered user automatically becomes the **Global Admin**
    (`isGlobalAdmin`). You never have to manually run SQL scripts to bootstrap
    admin access.

---

### Use Case 2: Adding Auth to Tier 1 Off-the-Shelf Apps (Grafana, Portainer, PGAdmin, etc.)

- **Difficulty Level:** **Minimal (Zero Code / 3 Docker Labels)**
- **What you actually have to do:**
  - Add the Traefik ForwardAuth middleware label to your container's
    `compose.yml`:
    ```yaml
    services:
      grafana:
        image: grafana/grafana:latest
        labels:
          - "traefik.enable=true"
          - "traefik.http.routers.grafana.rule=Host(`grafana.atyg.org`)"
          - "traefik.http.routers.grafana.middlewares=authyes-forwardauth@docker"
    ```
- **Why it's painless:**
  - Traefik intercepts unauthenticated requests at the network edge in $<1$ms
    before traffic reaches the container.
  - Auth-Yes validates the wildcard session cookie and injects
    `X-Forwarded-User: alice` downstream so Grafana automatically logs the user
    into their profile.

---

### Use Case 3: Adding Auth to Tier 2 Custom Web/SSR Apps (ed-droid, Hono, Next.js, Remix)

- **Difficulty Level:** **Minimal (2 Lines of Code)**
- **What you actually have to do:**
  - **Option A (Instant Ingress Hydration on first SSR byte):**
    ```typescript
    // Read the injected grant vector directly from the initial request:
    const userId = req.headers["x-forwarded-user-id"];
    const scopes = req.headers["x-forwarded-scopes"]?.split(",") || [];
    ```
  - **Option B (In-App SDK Route Guard with sub-30µs memory cache):**
    ```typescript
    import { authMiddleware, requireScope } from "@auth-yes/sdk/hono";

    app.use("/admin/*", authMiddleware(authSdk), requireScope("admin"));
    ```
- **Why it's painless:**
  - ForwardAuth injects pre-evaluated user identity and RBAC grants at the edge
    for instant SSR UI hydration.
  - In-app SDK verification leverages Valkey 8 RESP3 client tracking, validating
    tokens in local RAM in $<30\mu s$ without database round-trips.

---

### Use Case 4: Headless Edge Daemons & IoT Device Authentication

- **Difficulty Level:** **Low (RFC 9421 HTTP Message Signatures)**
- **What you actually have to do:**
  - Register the edge node's Ed25519 public key once via the admin API:
    ```bash
    curl -X POST https://auth.atyg.org/api/admin/hwk \
      -H "Cookie: session_id=..." \
      -d '{"jwk":{"kty":"OKP","crv":"Ed25519","x":"..."}, "name":"telemetry-drone-01"}'
    ```
  - Edge devices send signed HTTP requests with `Signature-Input` and
    `Signature` headers.
- **Why it's painless:**
  - Eliminates fragile static API tokens and shared secrets.
  - Signatures survive proxy TLS termination and are validated in $<5\mu s$ via
    Valkey $O(1)$ fingerprint set checks (`SISMEMBER auth:hwk:fingerprints`).

---

### Use Case 5: Zero-Touch Internal Microservice mTLS & SPIFFE Mesh

- **Difficulty Level:** **Minimal (Zero Manual Certificate Management)**
- **What you actually have to do:**
  - Internal backend daemons query the local SPIRE agent over a UNIX domain
    socket via `spire_ffi`.
  - The SDK automatically validates the client's SPIFFE ID (e.g.
    `spiffe://atyg.org/ed-droid`) against the authorized application registry.
- **Why it's painless:**
  - Native Rust FFI crate (`spire_ffi`) handles short-lived X.509 SVID rotation
    in the background every 60 minutes.
  - No manual PKI root management, zero CA expiration panics, and zero hardcoded
    mTLS secrets.

---

### Use Case 6: Live Telemetry & WebSockets (The Ghost Cockpit Protocol)

- **Difficulty Level:** **Minimal (1 Middleware Guard in Hono)**
- **What you actually have to do:**
  - Wrap your WebSocket endpoint with the session guard in `sdk/hono.ts`:
    ```typescript
    app.get(
      "/ws/telemetry",
      upgradeWebSocket((c) => {
        const token = getCookie(c, "session_id");
        const guard = createWebSocketGuard(authSdk, token);
        return {
          ...guard.handlers,
          onMessage(event, ws) {
            // Process telemetry data stream
          },
        };
      }),
    );
    ```
- **Why it's painless:**
  - When a session expires or is revoked, the SDK sends
    `{ "type": "AUTH_REVOKED", "reason": "SESSION_EXPIRED" }` and cleanly closes
    the socket.
  - The frontend freezes UI state in memory, triggers an ambient WebAuthn
    prompt, and seamlessly resumes telemetry without refreshing the page or
    losing user input.

---

### Use Case 7: User Device Loss & Zero-Downgrade Self-Recovery

- **Difficulty Level:** **Zero Admin Workload (Cryptographic Self-Service)**
- **What you actually have to do:**
  - **User Action:** The user visits `https://auth.atyg.org/recover`, types
    their 12-word BIP-39 recovery voucher, enters their recovery PIN, and
    touches their new replacement YubiKey or phone.
  - **Admin Action:** None.
- **Why it's painless:**
  - Uses the **2-of-3 Shamir's Secret Sharing (SSS) Matrix**:
    - _Share 1 (Device Share):_ Stored in browser IndexedDB, encrypted by
      WebAuthn PRF.
    - _Share 2 (Hot Share):_ Stored in server PostgreSQL, encrypted with
      Argon2id ($t=12, m=64\,\text{MiB}$).
    - _Share 3 (Cold Voucher):_ Printed 12-word phrase given to user during
      onboarding.
  - Combining any 2 shares reconstructs the master secret in client memory to
    enroll a new passkey.
  - Eliminates insecure SMS/email reset backdoors and relieves admins of manual
    account unlock tickets.

---

### Use Case 8: Incident Response & Fleet-Wide Session Revocation

- **Difficulty Level:** **Low (1-Click / Sub-30µs Mesh Invalidation)**
- **What you actually have to do:**
  - Click **"Revoke All Sessions"** for a compromised user or token in the
    Auth-Yes management dashboard.
- **Why it's painless:**
  - Valkey 8 RESP3 `BCAST` push tracking broadcasts invalidations across all
    backend nodes and edge proxies in $<30\mu s$.
  - Downstream microservices immediately drop L1 cache entries and sever active
    WebSocket feeds without polling loops or database queries.

---

### Use Case 9: Multi-App RBAC & Scope Provisioning

- **Difficulty Level:** **Low (Web UI Management or Invite Codes)**
- **What you actually have to do:**
  - **Option A (Admin Console):** Select User $\rightarrow$ Select Application
    $\rightarrow$ Assign Role (`admin`, `operator`, `viewer`).
  - **Option B (Automated Onboarding Invite):** Generate a pre-scoped invite
    link:
    ```bash
    curl -X POST https://auth.atyg.org/api/admin/invites/create \
      -H "Cookie: session_id=..." \
      -d '{"appId":"...", "role":"operator", "maxUses":1, "autoActivate":true}'
    ```
- **Why it's painless:**
  - New users redeeming the invite link automatically enroll their passkey and
    are provisioned with the exact role and scopes for that application.

---

### Use Case 10: Cryptographic Compliance & Tamper-Evident Audit Logging

- **Difficulty Level:** **Zero Operational Overhead (Append-Only RFC 6962
  Ledgers)**
- **What you actually have to do:**
  - Auditors query the cryptographically sealed audit ledger:
    ```bash
    curl https://auth.atyg.org/api/admin/audit/verify \
      -H "Cookie: session_id=..."
    ```
- **Why it's painless:**
  - Every login, invite redemption, scope grant, and session revocation is
    hashed into an append-only RFC 6962 Merkle Tree.
  - Produces Signed Tree Heads (STHs) and mathematical inclusion proofs. Even an
    adversary with direct `root` access to the PostgreSQL database cannot alter
    past audit logs without cryptographic detection.

---

### Use Case 11: Ephemeral Guest Sandboxes & Open Trial Access (Zero-Friction Demo to In-Flight Passkey Upgrade)

- **Difficulty Level:** **Minimal (1-Click Guest Issuance / Zero Passkey
  Required Upfront)**
- **What you actually have to do:**
  - **Option A (1-Click Guest Sandbox Access):** When a visitor clicks "Try
    Demo", issue a scoped ephemeral session:
    ```typescript
    // In ed-droid or host app:
    const res = await fetch("https://auth.atyg.org/api/guest/session", {
      method: "POST",
      body: JSON.stringify({ appId: "ed-droid", ttlSeconds: 7200 }),
    });
    // Sets wildcard session cookie on .atyg.org with scopes: ["guest", "trial"]
    ```
  - **Option B (Route Handler Trial Scoping):** Check the injected grant header:
    ```typescript
    app.get("/workspace", (c) => {
      const scopes = c.req.header("x-forwarded-scopes")?.split(",") || [];
      const isGuest = scopes.includes("guest") || scopes.includes("trial");

      return c.html(<Workspace isGuest={isGuest} />);
    });
    ```
  - **Option C (In-Flight Upgrade to Permanent Passkey):** When the guest clicks
    "Save Workspace", trigger ambient WebAuthn passkey registration on the spot
    without reloading the page or losing active session state.
- **Why it's painless:**
  - Eliminates the drop-off barrier of forcing passkey enrollment before users
    experience your product.
  - ForwardAuth transparently sets `X-Forwarded-Scopes: guest,trial` downstream.
  - Upgrades convert the ephemeral guest ID to a permanent passkey account
    seamlessly in memory.