178 lines
6.1 KiB
Markdown
178 lines
6.1 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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:**
|
|
```json
|
|
{
|
|
"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.
|