Tyler Gillispie f130b97838 docs: add engineering lifecycle and task protocols map to README and AGENTS.md

2026-08-25 12:25:26 -07:00

25 KiB

Raw Permalink Blame History

Custom IAM Architecture Analysis v2.md

Architectural Blueprint & Enterprise Implementation Roadmap: Decoupled Zero-Trust Identity Fabric

1. Executive Summary & Paradigm Evolution

The Auth-Yes Identity Fabric represents an ultra-low-friction, zero-trust Identity and Access Management (IAM) system tailored for a high-velocity microservice ecosystem. By rejecting the protocol bloat, redirect friction, and configuration overhead of traditional OIDC/OAuth2 monoliths (e.g., Keycloak, Authentik, Okta), Auth-Yes delivers microsecond-level stateful session verification, phishing-proof WebAuthn passkey authentication, and cryptographic workload identity.

Parent-Domain WebAuthn Scoping (RP_ID=atyg.org):
- Eliminates the runtime complexity of Related Origin Requests (ROR) for the primary domain ecosystem. All subdomains across *.atyg.org natively share passkeys and session verification.
Three-Tier Defense-in-Depth Model:
- Tier 1 (Global Edge Default): Universal Traefik ForwardAuth perimeter fallback protecting untagged/pre-release services.
- Tier 2 (Edge Proxy Override): ForwardAuth cookie validation for legacy/third-party applications (Portainer, Grafana, admin consoles).
- Tier 3 (Application Zero-Trust): In-app Deno App SDK communicating over high-throughput ConnectRPC / gRPC with SPIFFE/SPIRE mTLS identity and granular application RBAC.
Structured Token Provisioning Taxonomy:
- Formalized 3-tier invite token architecture (Global Admin, Site-Scoped, and Open/Pending) alongside Out-of-Band Account Recovery.
Complete Administrative Console Roadmap:
- Finalized UI specifications for Application Registration (/admin/apps), Multi-Type Invite Provisioning (/admin/invites), and Granular User RBAC Grant Management (/admin/users/:id).

📘 Practical Playbook & 11 High-ROI Use Cases: Step-by-step guides for Appliance Setup, Traefik ForwardAuth, SSR Hydration, Live WebSockets, Ephemeral Trial/Guest Tokens, and SSS Recovery.
- Raw Gitea Mirror: https://git.atyg.org/tylerg/auth-yes/raw/branch/main/docs/USE_CASES_AND_EFFORT.md
⚡ The Ghost Cockpit Protocol Spec: Specification and client snippet for non-destructive WebSocket telemetry freezes and in-flight WebAuthn re-auth.
- Raw Gitea Mirror: https://git.atyg.org/tylerg/auth-yes/raw/branch/main/docs/GHOST_COCKPIT_SPEC.md
🌐 ForwardAuth Browser Redirection & Deep-Link Spec: Specification for browser 302 vs API 401 dual-response handling, open redirect prevention (CWE-601), and deep-link query parameter preservation.
- Raw Gitea Mirror: https://git.atyg.org/tylerg/auth-yes/raw/branch/main/docs/FORWARDAUTH_REDIRECT_SPEC.md
🛡️ Cryptographic Standards & Verification Dossier: Full mathematical and specification audits (W3C WebAuthn Level 3, RFC 9421, RFC 7638, RFC 6962, RFC 9106).
📦 Raw SDK Module Distribution: https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts

🛠️ Engineering Lifecycle & Task Protocols

Auth-Yes development follows a strict, disciplined 4-step task lifecycle designed to preserve context, prevent regressions, and enforce dual-level deliberation between human developers and AI agents.

flowchart LR
    subgraph Lifecycle ["Sequential Engineering Lifecycle"]
        direction LR
        P["1. plan<br/>(tasks/plan.md)"] --> A1["2. audit-1<br/>(tasks/audit-1.md)"]
        A1 --> D["3. do<br/>(tasks/do.md)"]
        D --> A2["4. audit-2<br/>(tasks/audit-2.md)"]
    end

    subgraph Standalone ["On-Demand / Any Time"]
        DBG["debug<br/>(tasks/debug.md)"]
    end

    DBG -.->|"Feeds Root Cause into"| P

Protocol Quick Reference

Step / Tool	Protocol File	Role	Purpose	Direct Command	Prompt Prep Command
1	`tasks/plan.md`	System Analyst	Deep codebase research & drafting task in `tasks/new/`	`tasks/plan XYZ`	`tasks/plan a prompt for Jules`
2	`tasks/audit-1.md`	Plan Critic	5-point plan audit, scoring, and refinement	`tasks/audit-1 task #1`	`tasks/audit-1 prompt for Jules`
3	`tasks/do.md`	Developer	Execution, state machine (`wip/` `\rightarrow` `complete/`), quality gates	`tasks/do task #1`	`tasks/do a prompt for Jules`
4	`tasks/audit-2.md`	QA Auditor	Post-implementation code quality & zero-regression audit	`tasks/audit-2 branch`	`tasks/audit-2 prompt for Jules`
🔬	`tasks/debug.md`	Investigator	Hermetic root-cause analysis & experiments in `scratch/`	`tasks/debug issue`	`tasks/debug a prompt for Jules`

For master guidelines and orchestrator index, see tasks/path.md and tasks/GUIDELINES.md.

2. Core Security Architecture & Defense-in-Depth Layering

Auth-Yes implements a strict multi-layered defense model ensuring that neither network locality nor perimeter isolation is treated as an implicit proxy for trust.

                 [ Public Internet / Client Browser ]
                                 │
                                 ▼
        ═══════════════════════════════════════════════════
        TIER 1 & 2: Traefik Reverse Proxy & ForwardAuth Edge
        ═══════════════════════════════════════════════════
            │                                      │
(Legacy/3rd-Party Apps)                 (Native Microservices)
[ Portainer / Web UIs ]                 [ ed-droid Web Edge ]
            │                                      │
            ▼                                      ▼
ForwardAuth Interception               Traefik TLS Ingress
GET /api/forward-auth                  PassTLSClientCert
(Valkey Cache Lookup)                              │
            │                                      ▼
            └──────────────────────────────► ═══════════════════════════
                                             TIER 3: Zero-Trust App Mesh
                                             ConnectRPC + SPIFFE / mTLS
                                             ═══════════════════════════
                                                           │
                                                           ▼
                                               [ Auth-Yes Core Gateway ]
                                               - Valkey Cache (L1/L2)
                                               - PostgreSQL Store
                                               - Default-Deny RBAC

2.1. Tier 1 — Global Edge Perimeter (Traefik ForwardAuth Default Fallback)

Objective: Ensure zero accidental exposure of internal or pre-release services.
Mechanism: Traefik entrypoints (e.g., websecure) are configured with a default ForwardAuth middleware. Any newly created container or untagged service deployed on the internal network is protected by default.
Behavior: Unauthenticated HTTP requests without a valid session cookie are automatically redirected to https://auth.atyg.org/login.

2.2. Tier 2 — Edge Proxy Override (Third-Party & Legacy Applications)

Objective: Secure off-the-shelf and legacy software (e.g., Portainer, Grafana, PgAdmin) without requiring code modifications or custom SDK integration.
Mechanism: Traefik routers for these services explicitly route authentication checks to https://auth.atyg.org/api/forward-auth.
Validation Flow:
1. Client sends request with session_id cookie scoped to .atyg.org.
2. Traefik queries auth-api:8000/api/forward-auth.
3. Auth API checks Valkey in microseconds. If valid and account is active, returns HTTP 200 OK and injects upstream identity headers:
  - X-Forwarded-User: <username>
  - X-Forwarded-User-Id: <uuid>
4. If invalid or missing, returns HTTP 401 Unauthorized or redirects to login.

2.3. Tier 3 — Application-Level Zero-Trust (Deno App SDK + ConnectRPC + SPIFFE/mTLS)

Objective: Provide high-throughput, microsecond-latency identity validation with granular Role-Based Access Control (RBAC) for native microservices.
Mechanism:
- Subsidiary services import the logic-pure @ed-droid/auth-yes/sdk middleware.
- The SDK intercepts requests, extracts the session token, and validates it against the Auth Hub using ConnectRPC / gRPC over HTTP/2 multiplexed connections.
- Workload Cryptographic Attestation: Workload identity is authenticated via SPIFFE/SPIRE x509 SVID certificates. The Auth Hub validates the calling application's SPIFFE ID (e.g., spiffe://system.local/ed-droid-backend) against the apps table.
- Default-Deny Authorization: Authentication (who the user is) is decoupled from authorization (what app they can access). The Auth Hub verifies that an explicit active record exists in the grants table matching (user_id, app_id).

3.1. Parent Domain Scoping (`RP_ID=atyg.org`)

In the W3C WebAuthn specification, a credential is bound to a Relying Party Identifier (RP_ID).

Under WebAuthn origin validation rules, an RP_ID can be set to any registrable domain suffix (eTLD+1) of the origin.

By setting:

RP_ID=atyg.org
ORIGIN=https://auth.atyg.org

Result: Any passkey created under RP_ID=atyg.org is cryptographically valid and authenticatable across all subdomains under *.atyg.org (e.g., auth.atyg.org, ed-droid.atyg.org, nas.atyg.org).
Browser Compliance: Supported natively across 100% of modern WebAuthn implementations (Apple Safari/iOS, Google Chrome/Android, Windows Hello, 1Password, YubiKeys).

To support edge proxy interception (ForwardAuth Tier 1 & 2), the Auth Hub sets the session cookie with domain wildcard scoping:

setCookie(c, "session_id", sessionId, {
  domain: ".atyg.org",
  httpOnly: true,
  secure: true,
  sameSite: "Lax",
  expires: expiresAt,
});

This ensures the browser transmits the session cookie seamlessly to all subdomains under *.atyg.org.

Dynamic Related Origin Requests via https://auth.atyg.org/.well-known/webauthn are officially archived for Phase 3 (Cross-TLD Expansion). ROR will only be required when federating authentication across completely distinct root domains (e.g., bridging atyg.org with ed-droid.io or independent-domain.com).

4. Identity Lifecycle & Token Provisioning Taxonomy

Auth-Yes implements a strict 3-tier invite provisioning architecture ensuring mathematical control over user onboarding and access grants.

                     ┌────────────────────────────────────────┐
                     │       Admin Onboarding Generator       │
                     └───────────────────┬────────────────────┘
                                         │
         ┌───────────────────────────────┼──────────────────────────────┐
         ▼                               ▼                              ▼
┌──────────────────┐           ┌──────────────────┐           ┌──────────────────┐
│   Type 1: Global │           │   Type 2: Site   │           │  Type 3: General │
│   Admin Invite   │           │   Scoped Invite  │           │  Open / Pending  │
├──────────────────┤           ├──────────────────┤           ├──────────────────┤
│ app_id: NULL     │           │ app_id: UUID     │           │ app_id: NULL     │
│ role: 'admin'    │           │ role: 'user/adm' │           │ role: 'user'     │
│ status: 'active' │           │ status: 'active' │           │ status: 'pending'│
└──────────────────┘           └──────────────────┘           └──────────────────┘

4.1. Type 1: Global Admin Onboarding Token

Purpose: Initial system bootstrapping and administrative team onboarding.
Characteristics: app_id is unbound (NULL or Management Console), role = 'admin'.
Lifecycle: User registers passkey \rightarrow Account is set to active \rightarrow User is granted global administrative privileges across Auth-Yes and all internal systems.

4.2. Type 2: Site-Scoped Onboarding Token

Purpose: Controlled user onboarding for a specific subsidiary application (e.g., ed-droid).
Characteristics: app_id is locked to a specific application UUID, role = 'user' (or application admin).
Lifecycle: User registers passkey \rightarrow Account is set to active \rightarrow System automatically inserts a grant record into grants (user_id, app_id, role). User can access the designated application immediately, but is denied access to all other apps.

4.3. Type 3: General Open / Pending Registration Token

Purpose: Broad community or team registration requiring manual verification.
Characteristics: app_id: NULL, role = 'user', initial account_status = 'pending'.
Lifecycle: User registers passkey \rightarrow Account is created in pending state \rightarrow User cannot log in until a Global Admin accesses /admin/users and activates the account, optionally assigning specific application grants.

4.4. Out-of-Band Single-Use Account Recovery Token

Purpose: Lockout recovery when a user loses all registered hardware passkeys.
Characteristics: 24-hour time-limited cryptographic token linked to existing user_id.
Lifecycle: Admin generates recovery link in /admin/users/:id \rightarrow Transmitted out-of-band \rightarrow User accesses /recovery?code=... \rightarrow User binds new hardware passkey \rightarrow Previous passkeys invalidated, existing UUID and application grants preserved.

4.5. The RBAC Grant Lifecycle: Default-Deny, Assignment Matrix & RPC Payload

The identity fabric enforces strict decoupled authorization governed by three continuous states:

The Baseline (Default-Deny Zero-Trust):
- When a user registers a passkey or when an admin provisions an account, the user possesses zero application access by default.
- If an unassigned user attempts to authenticate to ed-droid.atyg.org, the calling application SDK queries the central AuthService.validateSession endpoint over ConnectRPC.
- The Auth Hub queries SELECT role FROM grants WHERE user_id = $1 AND app_id = $2. Finding no matching grant record, the server returns { valid: false, uuid: "", scopes: [], error: "Validation failed" }, resulting in an instant 403 Forbidden: No explicitly granted roles.
The Assignment Matrix (Admin Console):
- In https://auth.atyg.org/admin:
  - Under Applications (/admin/apps), apps are registered (e.g. ed-droid, SPIFFE ID spiffe://system.local/ed-droid-backend).
  - Under User Profile (/admin/users/:id), the administrator views the user's active permissions matrix.
  - To grant access to a user (e.g., your nephew), the administrator selects ed-droid from the app selector, selects a role (viewer, operator, editor, admin), and clicks Grant Access (or checks the matrix toggle).
  - An atomic row is written to grants (user_id, app_id, role).
The Payload & Runtime Authorization:
- The next time the user makes a request to ed-droid, the Deno App SDK intercepts the session token and validates it via ConnectRPC over internal mTLS.
- The Auth Hub validates the session in Valkey, retrieves the active grant for ed-droid, and returns the cryptographic payload:
```
{
  "valid": true,
  "uuid": "edfa8a54-66c5-4444-9e38-becfc5aa6463",
  "scopes": ["viewer"]
}
```
- The Deno App SDK middleware injects c.set("user", { uuid, scopes: ["viewer"] }) into the application context, allowing ed-droid to render the exact UI views and API actions permitted for a viewer.

5. PostgreSQL Central Identity Schema Reference

-- Central Users Table
CREATE TABLE IF NOT EXISTS users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  username TEXT UNIQUE NOT NULL,
  display_name TEXT,
  account_status TEXT DEFAULT 'pending' CHECK (account_status IN ('active', 'pending', 'suspended')),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Registered Applications / Sites Table
CREATE TABLE IF NOT EXISTS apps (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  spiffe_id TEXT UNIQUE NOT NULL,
  description TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Granular Application RBAC Grants Table
CREATE TABLE IF NOT EXISTS grants (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  app_id UUID NOT NULL REFERENCES apps(id) ON DELETE CASCADE,
  role TEXT NOT NULL DEFAULT 'user',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(user_id, app_id)
);

-- Onboarding & Invitation Tokens Table
CREATE TABLE IF NOT EXISTS invites (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  code TEXT UNIQUE NOT NULL,
  app_id UUID REFERENCES apps(id) ON DELETE CASCADE,
  role TEXT NOT NULL DEFAULT 'user',
  used_by UUID REFERENCES users(id) ON DELETE SET NULL,
  expires_at TIMESTAMPTZ NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  used_at TIMESTAMPTZ
);

-- Hardware Passkeys Table
CREATE TABLE IF NOT EXISTS passkeys (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  credential_id TEXT UNIQUE NOT NULL,
  public_key TEXT NOT NULL,
  counter BIGINT NOT NULL DEFAULT 0,
  aaguid TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Active User Sessions Table
CREATE TABLE IF NOT EXISTS sessions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  expires_at TIMESTAMPTZ NOT NULL
);

-- Security Audit Records Table
CREATE TABLE IF NOT EXISTS audit_records (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE SET NULL,
  action TEXT NOT NULL,
  resource TEXT,
  details JSONB,
  ip_address TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enterprise Hardware AAGUID Allowlist Table
CREATE TABLE IF NOT EXISTS aaguid_allowlist (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  aaguid TEXT UNIQUE NOT NULL,
  description TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

6. Administrative UI Implementation Specifications

The Auth-Yes Admin Console is built using server-rendered Deno Hono JSX components executing direct database queries with zero intermediate loopback latency.

6.1. Navigation Architecture (`AuthenticatedLayout.tsx` & `AdminLayout.tsx`)

[ Identity Provider Navbar ]
  ├── User Dashboard (/dashboard)
  ├── Active Sessions (/dashboard/sessions)
  ├── Registered Passkeys (/dashboard/passkeys)
  └── [ ADMIN CONSOLE ] (Rendered if isAdmin = true)
        ├── User Directory (/admin/users)
        ├── Application Registry (/admin/apps)
        ├── Invite Tokens (/admin/invites)
        ├── AAGUID Allow-List (/admin/aaguid)
        └── Security Audit Logs (/admin/audit-logs)

6.2. Page Specifications & Actions

1. User Directory (`/admin/users`)

Features:
- Tabular list of all registered users (username, display_name, account_status, created_at, grant_count).
- Status mutation buttons: Activate, Suspend, Re-Activate.
- Link to detailed User Management profile (/admin/users/:id).

2. User Profile & RBAC Grant Manager (`/admin/users/:id`)

Features:
- Account Recovery: Single-click Generate 24h Out-of-Band Recovery Link.
- Active Sessions: List active sessions with individual and Revoke All actions.
- Registered Hardware Tokens: List registered passkeys (credential_id, counter, created_at) with Delete Device action.
- Application Access Grants (New in v2):
  - Matrix of currently assigned application access (App Name, Role, Granted At).
  - Grant Access dropdown selector (App, Role: user | admin) to attach new app permissions.
  - Revoke Access button to remove application-specific access.

3. Application Registry (`/admin/apps`)

Features:
- Table of all registered internal applications (name, spiffe_id, description, active_users_count).
- Register New Application form:
  - App Name (e.g., "Elite Dangerous Streaming Hub")
  - SPIFFE ID (e.g., spiffe://system.local/ed-droid-backend)
  - Description
- Delete Application action (with confirmation modal preventing accidental lockout).

4. Invite & Onboarding Token Manager (`/admin/invites`)

Features:
- Token Generation Modal/Form:
  - Token Type Selector:
    1. Global Admin Token (Pre-configures role: 'admin', app: NULL)
    2. Site-Scoped Token (Displays App dropdown selector + Role selector)
    3. Open/Pending User Token (Pre-configures role: 'user', app: NULL, creates pending user)
  - Expiration Bounds: 1 to 30 days (default: 7 days).
  - Custom Invite Code (Optional): Auto-generates cryptographically random code if left blank.
- Live Invites Ledger:
  - Table displaying Code, Type / Scope, Target App, Role, Expires At, Status (Active / Used / Expired).
  - Single-click Copy Registration URL button (https://auth.atyg.org/register?code=...).
  - Revoke Invite action.

7. Implementation Roadmap & Execution Checklist

Phase	Milestone	Scope / Deliverables	Status
Phase 1	Core Identity & Passkey Engine	- WebAuthn challenge & verification engine - PostgreSQL schema auto-initialization - Valkey session cache & instant revocation - Direct SSR database rendering (zero-loopback) - Hybrid hardware/software passkey support	COMPLETED
Phase 2	Zero-Trust App Mesh (Backend)	- ConnectRPC / gRPC transport - SPIFFE/SPIRE mTLS client certificate validation - Default-deny RBAC grant verification - ForwardAuth `/api/forward-auth` endpoint	COMPLETED
Phase 3	Admin Console UI Views (Current)	- `/admin/apps` Application Registry UI - `/admin/invites` Multi-Type Token Provisioning UI - `/admin/users/:id` App RBAC Grant Manager UI - Domain wildcard cookie (`.atyg.org`) deployment	READY FOR BUILD
Phase 4	Edge Hardening & Future Scoping	- Traefik Tier 1 global ForwardAuth fallback configuration - Traefik Tier 2 ForwardAuth container routing - Related Origin Requests (`/.well-known/webauthn`) for external TLDs	FUTURE

8. License

Auth-Yes is dual-licensed under:

MIT License (LICENSE-MIT)
Apache License, Version 2.0 (LICENSE-APACHE)

SPDX-License-Identifier: MIT OR Apache-2.0

25 KiB Raw Permalink Blame History