tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
auth-yes/docs/USE_CASES_AND_EFFORT.md

11 KiB
Raw Blame History

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 10 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  │
└────┴─────────────────────────────────────────────────┴──────────────────┴────────────────────────┘

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: 
      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): 
      // 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): 
      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: 
      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: 
      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: 
      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: 
      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.