auth-yes/docs/V3_AUDIT_REPORT.md

V3 IAM & Web UI Architectural Audit Report

1. System Implementation Status Matrix

Component / Layer	Status	Implementation Details & File References
Auth Hub / Core Gateway Engine	[Completed]	auth-yes/server/main.ts: WebAuthn registration/login challenge & verify, direct database schema auto-init, Valkey session caching with TTL, sliding-window rate limiting, structured audit logging.
Session & Authorization Engine	[Completed]	auth-yes/server/auth-session.ts: Dual-layer session validation (Valkey cache + PostgreSQL fallback), global admin role detection.
Workload Identity & Zero-Trust Mesh	[Completed]	ConnectRPC / gRPC service with HTTP/2 multiplexing, SPIFFE/SPIRE x509 SVID mTLS client certificate authentication (spire_ffi Rust FFI), default-deny RBAC matching apps and grants.
Direct Server-Side Rendering (SSR)	[Completed]	auth-yes/ui/mod.ts: 100% in-process database & session queries for all UI routes, eliminating error-prone internal HTTP loopback fetches to 127.0.0.1:8000.
Docker Build Layer Caching	[Completed]	auth-yes/Dockerfile & auth-yes/deps.ts: Dedicated dependency caching layer reducing rebuild times from 20s to ~1s.
Client-Side WebAuthn Mechanics	[Completed]	auth-yes/ui/public/auth-client.js: Standard navigator.credentials handling for WebAuthn passkeys with robust error parsing.
User Directory & Account Status	[Completed]	auth-yes/ui/components/AdminUsersPage.tsx: User list, status toggles (Activate, Suspend, Re-Activate).
User Profile & Device Revocation	[Completed]	auth-yes/ui/components/AdminUserDetailsPage.tsx: Active sessions review & revocation, passkey device deletion, 24h Out-of-Band recovery link generation.
AAGUID Allow-List Management	[Completed]	auth-yes/ui/components/AAGUIDPage.tsx: Enterprise hardware AAGUID allow-list table and registration form.
Security Audit Logs	[Completed]	auth-yes/ui/components/AuditLogPage.tsx: Live audit trail of logins, registrations, status changes, and security events.
Connected Apps / Sites Registry UI	[Pending]	Backend apps table exists and ConnectRPC enforces it, but UI view (/admin/apps) to register/view applications is pending.
Multi-Type Invite Token Manager UI	[Pending]	Backend /api/admin/invites/create exists, but dedicated UI (/admin/invites) to generate Global Admin, Site-Scoped, and Open/Pending tokens with live ledger is pending.
User App RBAC Grants Manager UI	[Pending]	Database grants table and ConnectRPC scopes payload exist, but UI matrix on /admin/users/:id to assign/revoke app permissions per user is pending.
ForwardAuth Edge Proxy Route	[Pending]	Traefik ForwardAuth endpoint (/api/forward-auth) for Tier 2 legacy apps (Portainer, etc.) and wildcard .atyg.org cookie scoping.

---

2. Architectural Refinements Captured in V3

2.1. WebAuthn Scope: Parent Domain (RP_ID=atyg.org) vs. ROR

• Previous Assumption: Assumed Related Origin Requests (ROR) via dynamic /.well-known/webauthn was required to share passkeys between auth.atyg.org and ed-droid.atyg.org.
• V3 Architectural Finding: Under W3C WebAuthn Level 3 (eTLD+1 rules), declaring RP_ID=atyg.org on https://auth.atyg.org allows all subdomains (*.atyg.org) to natively share passkeys across all browsers without ROR overhead.
• Resolution: ROR is archived as a Phase 5 feature reserved strictly for future cross-TLD federations (e.g. bridging atyg.org with external root domains).

2.2. Three-Tier Defense-in-Depth Model

1. Tier 1 (Global Edge Default): Default Traefik ForwardAuth middleware applied to entrypoints, preventing exposure of untagged or pre-release containers.
2. Tier 2 (Edge Proxy Override): Traefik ForwardAuth route (/api/forward-auth) verifying .atyg.org session cookies in Valkey and injecting X-Forwarded-User headers for third-party web UIs (Portainer, Grafana, PgAdmin).
3. Tier 3 (Zero-Trust App Mesh): In-app Deno SDK communicating over ConnectRPC + SPIFFE/SPIRE mTLS with default-deny RBAC for native microservices (ed-droid).

2.3. Formatted 3-Tier Invite Token Taxonomy

1. Global Admin Invite Token: app_id: NULL, role: 'admin', creates active administrator.
2. Site-Scoped Invite Token: app_id: <app-uuid>, role: 'user' (or app role), auto-activates user and binds app grant upon passkey enrollment.
3. General Open / Pending Onboarding Token: app_id: NULL, role: 'user', creates account in pending status for manual admin approval.
4. (Plus Out-of-Band Single-Use Account Recovery Token).

2.4. Explicit RBAC Lifecycle Paradigm

• Baseline (Zero-Trust Default-Deny): Newly provisioned user has zero application access. Accessing ed-droid returns HTTP 403 Forbidden.
• Assignment (Admin Console Matrix): Administrator navigates to /admin/users/:id or RBAC Matrix, selects ed-droid, and assigns a role (viewer, operator, editor, admin).
• Payload & Enforcement: Next time the user accesses ed-droid, ConnectRPC returns { valid: true, uuid: "...", scopes: ["viewer"] }, granting immediate runtime access.

---

3. Pending Implementation Roadmap

1. Build Application Registry UI (/admin/apps):
   • Table of registered apps (name, spiffe_id, description, created_at, active_users_count).
   • Register Application form (name, spiffe_id, description).
   • Delete application action with confirmation modal.
2. Build Multi-Type Invite Token Manager UI (/admin/invites):
   • Generation Form supporting all 3 token types (Global Admin, Site-Scoped with App dropdown, Open/Pending).
   • Live ledger of active, used, and expired tokens with single-click copy links (https://auth.atyg.org/register?code=...) and revoke actions.
3. Build User App RBAC Grants Matrix UI (/admin/users/:id):
   • Table of user's active application access grants (App Name, Role, Granted At).
   • Add Grant dropdown form (App Selector, Role Selector: viewer | operator | editor | admin).
   • Revoke Grant action button.
4. Deploy Domain Wildcard Cookie (.atyg.org) & ForwardAuth Route:
   • Update session cookie creation with domain: ".atyg.org".
   • Add GET /api/forward-auth endpoint in auth-yes for Traefik Tier 2 edge proxy validation.