auth-yes/docs/DUAL_AUDIENCE_DEVELOPMENT_GUIDE.md

Dual-Audience Development Guide: Agent-First APIs & Mobile-First SSR UI

This guide outlines the architectural blueprint and best practices for building modern services within the Auth-Yes Zero-Trust Ecosystem.

---

1. The Core Philosophy: Dual-Audience Architecture

Every modern application should be built for two primary audiences:

1. 🤖 AI Agents & Workloads (Primary Data Consumer):
   • Headless execution via Model Context Protocol (MCP), REST APIs, or ConnectRPC.
   • Machine-readable, high-density JSON/RPC responses with zero HTML/CSS clutter.
   • Authentication via Delegated Bearer Tokens (ay_sess_...) or mTLS SPIFFE workload identities.
2. 📱 Humans on Mobile Devices (Primary UI Consumer):
   • Ultra-fast, zero-friction Server-Side Rendered (SSR) JSX touch cards.
   • Passkey (WebAuthn) biometric authentication.
   • Single Sign-On (SSO) entry via the Auth-Yes Application Launchpad.

---

2. Architectural Blueprint for Subsidiary Apps (e.g. ed-droid)

                 +---------------------------------------+
                 |         Traefik Edge Ingress          |
                 +---------------------------------------+
                                     |
               ForwardAuth Check     |  (Injects X-Forwarded-*)
            +------------------------+------------------------+
            |                                                 |
            v                                                 v
+-----------------------+                         +-----------------------+
|   Auth-Yes Service    |                         |    Subsidiary App     |
| (Validates Session /  |                         |   (e.g., ed-droid)    |
|  Bearer Token)        |                         +-----------------------+
+-----------------------+                                     |
                                                              |
                                 +----------------------------+----------------------------+
                                 |                                                         |
                                 v                                                         v
                      [ /api/* JSON Endpoints ]                                 [ SSR HTML Mobile Cards ]
                      - Served for AI Agents & MCP                              - Served for Human Browsers
                      - Filtered by Scopes / Roles                              - Clean, high-contrast UI

---

3. How to Build an "Agent-First" Subsidiary App

Step 1: Ingress Protection via ForwardAuth

In your Traefik/Compose configuration, protect your service domain with Auth-Yes ForwardAuth middleware:

labels:
  - "traefik.http.routers.ed-droid.middlewares=auth-yes-forwardauth@docker"

When requests arrive:

• Traefik queries http://auth-api:8000/api/forward-auth.
• Auth-Yes validates either the browser's session_id cookie or the incoming Authorization: Bearer ay_sess_... token.
• If authorized, Traefik injects:
  • X-Forwarded-User: <username>
  • X-Forwarded-User-Id: <uuid>
  • X-Forwarded-Scopes: <scope1,scope2>
  • X-Forwarded-App-Id: <app_id>

Step 2: Implement Clean JSON API Routes

Provide standard JSON endpoints for all core operations:

import { Hono } from "jsr:@hono/hono";

const app = new Hono();

// AI Agents & APIs consume JSON directly:
app.get("/api/fleet", (c) => {
  const user = c.req.header("X-Forwarded-User");
  const fleetData = getFleetForUser(user);
  return c.json({ fleet: fleetData });
});

Step 3: Progressive Content Negotiation (Optional)

If a route serves both humans and AI agents without separate /api prefixes, inspect the Accept header or ?format=json query:

app.get("/ships/:id", (c) => {
  const ship = getShip(c.req.param("id"));

  // If requested by an agent or CLI:
  if (
    c.req.header("Accept")?.includes("application/json") ||
    c.req.query("format") === "json"
  ) {
    return c.json(ship);
  }

  // If requested by a human browser:
  return c.html(ShipCardView({ ship }));
});

---

4. Connecting AI Agents via Model Context Protocol (MCP)

To expose your subsidiary applications to AI assistants (Antigravity, Jules, Claude Desktop):

1. Mint a Delegated Session in Auth-Yes:

   • Go to https://auth.atyg.org/dashboard/sessions \rightarrow Click + Delegate Agent Session.
   • Set Label: "Antigravity Assistant", Lifespan: 12 Hours, Scope: ed-droid.
   • Copy the CLI export string.

2. Configure the MCP Server:

   {
     "mcpServers": {
       "ed-droid": {
         "command": "deno",
         "args": [
           "run",
           "-A",
           "https://git.atyg.org/tylerg/ed-droid/raw/branch/main/mcp/server.ts"
         ],
         "env": {
           "AUTH_YES_TOKEN": "ay_sess_8de186f564d7..."
         }
       }
     }
   }
   

3. Tool Call Execution: The MCP server attaches Authorization: Bearer $AUTH_YES_TOKEN to all internal fetch calls, gaining instant authorized access to fleet telemetry and data with full Merkle audit attribution!

---

5. Ephemeral Guest & Support Passes (Magic 1-Click Links)

In addition to Agent Bearer Tokens, Auth-Yes supports Ephemeral Magic Passes for friends and external support technicians:

The Flow:

1. Spawn Pass: Under Sessions, click + Spawn Guest / Support Pass:
   • Label: "Friend Demo - Elite Dangerous Fleet"
   • Lifespan: 2 Hours (auto-expires)
   • Target App: ed-droid.atyg.org
2. Share 1-Click Link: https://auth.atyg.org/pass?token=ay_pass_9f8a7b6c...
3. Instant Redemption:
   • When opened in any browser, Auth-Yes automatically sets the .atyg.org session cookie with restricted scopes.
   • The browser is immediately redirected to https://ed-droid.atyg.org.
   • Zero friction: No passkeys to register, no passwords, no email confirmation.
4. Security & Control:
   • The guest only has access to the specified target app.
   • The pass is visible on your Sessions dashboard in real time with an instant [Revoke] button.