# 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`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/auth-yes/Dockerfile) & [`auth-yes/deps.ts`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/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`](file:///home/tylerg/p/data/ed-droid/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: `, `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.