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

15 KiB
Raw Permalink 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 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 │
│ 12 │ Hybrid Cloud Edge & Remote Tunnel Ingress       │ Low              │ Zero-Touch Tunnel / DoH│
└────┴─────────────────────────────────────────────────┴──────────────────┴────────────────────────┘

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:
    • Dual-Response Protocol: If a human opens a protected app in a browser (Accept: text/html), Auth-Yes immediately issues a 302 Redirect to https://auth.atyg.org/login?redirect=.... Upon touching their passkey, the user is automatically bounced back to the exact URL/tab they originally requested.
    • Headless & API Transparency: Background scripts, daemons, and cURL calls receive clean 401 Unauthorized responses without getting stuck in HTML redirect loops.
    • Open Redirect Protection (CWE-601): The return URL is strictly validated against approved domains (*.atyg.org and localhost) to eliminate phishing attack vectors.
    • Auth-Yes validates the wildcard session cookie and injects X-Forwarded-User: alice downstream so Grafana or Portainer 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.

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

Use Case 12: Hybrid Cloud Edge & Remote Tunnel Ingress (Cloudflare Tunnel, Split-Horizon DNS & WAN Resiliency)

  • Difficulty Level: Low (Zero-Touch Tunnel Ingress / Transparent Split-Horizon)
  • What you actually have to do:
    1. Map public hostnames in Cloudflare Zero Trust Tunnels (cloudflared) pointing auth.atyg.org and downstream subdomains (e.g. ed-droid.atyg.org) to internal Traefik (http://192.168.1.10:80 or https://192.168.1.10:443 with "No TLS Verify").
    2. Local LAN devices resolve directly to 192.168.1.10 via local router/DNS, while remote mobile clients resolve via Cloudflare Anycast edge proxies.
    3. Auth-Yes handles ForwardAuth 302 redirects and session cookie scoping transparently across both local LAN and remote WAN ingress vectors.
  • Audit & Architectural Resilience Verification Requirements:
    • Cookie Scope Parity: Ensure Set-Cookie with wildcard domain .atyg.org is preserved across reverse proxy tunnels without origin truncation.
    • Open-Redirect & Deep-Link Preservation: Verify https://auth.atyg.org/login?redirect=... deep-links survive multi-hop proxies and DoH mobile resolvers.
    • Negative DNS Caching & Mobile DoH Isolation: Validate system behavior when client mobile OS resolvers transition between Wi-Fi split-horizon DNS and cellular DNS over HTTPS (DoH).
    • Latency SLA: Verify ForwardAuth edge lookup latency remains <50\mu s on internal LAN and $<10$ms over Cloudflare Tunnel edge.