# Identity Provider Architecture Audit Report

## 1. Implementation Status Matrix

| Component                                                                             | Status        | File Paths / Notes                                                                                                                                                                                                                  |
| :------------------------------------------------------------------------------------ | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Gateway / Auth Hub (Deno/Hono service)**                                        | [In Progress] | `auth-yes/server/main.ts` (Endpoints exist as `501 Not Implemented` stubs), `core/api-server.ts` (Partial implementations in main app)                                                                                              |
| **Auth UI (administration, activation, recovery, and session review)**                | [Pending]     | No Auth UI implementation or `auth-ui` Compose service exists, although the target architecture requires both.                                                                                                                      |
| **Shared App SDK (Middleware and API-client wrappers)**                               | [In Progress] | `auth-yes/sdk/mod.ts` (Basic class structure exists, missing Valkey Client-Side Caching with RESP3 Invalidation)                                                                                                                    |
| **PostgreSQL Identity Schema**                                                        | [In Progress] | `core/db.ts` implements Users, Passkeys, Edge_nodes, and Sessions, but lacks application metadata, RBAC and invitation records, audit records, account status, and `display_name` required by the specification.                    |
| **Valkey Session Cache Integration**                                                  | [Pending]     | Mentioned in setup (`infrastructure/setup.ts` `auth-valkey`) but no actual integration logic in code yet.                                                                                                                           |
| **Monorepo Workspace (deno.json) & Multi-stage Dockerfile**                           | [Pending]     | `deno.json` is completely missing. Dockerfiles (`Dockerfile`, `auth-yes/Dockerfile`) exist but are single-stage and need multi-stage refinement.                                                                                    |
| **Setup CLI Utility (infrastructure/setup.ts & compose generators)**                  | [In Progress] | `infrastructure/setup.ts` supports `.env.auth` and `compose.auth.yml` generation, but lacks some strict zero-trust configs.                                                                                                         |
| **WebAuthn Registration, Authentication & Related Origins**                           | [In Progress] | `core/api-server.ts` implements basic ceremonies, but uses `attestationType: "none"` and does not provide the required `/.well-known/webauthn` Related Origins document. `auth-yes/server/main.ts` contains only stubbed endpoints. |
| **Add-on Modules (Audit Logging, Invite Codes, Hardware Attestation, Rate Limiting)** | [Pending]     | No implementation yet for MDS3 attestation verification, rate limiting, audit logging, or invite codes.                                                                                                                             |
| **Identity Lifecycle & Administration**                                               | [Pending]     | No implementation exists for account activation, additional passkey enrollment/removal and recovery, profile updates, or session/activity review.                                                                                   |

## 2. Architectural Deviations & Technical Trade-offs

During the recent development sessions, several compromises and deviations were
made from the target architecture:

- **gRPC Postponed**: The Auth API Gateway (`auth-yes/server/main.ts`) and SDK
  (`auth-yes/sdk/mod.ts`) are currently relying on standard HTTP/REST endpoints
  rather than the gRPC transport required by the target architecture. No gRPC
  service or Protocol Buffer contract is currently present.
- **Centralized DB Schema Coupling**: The PostgreSQL initialization in
  `core/db.ts` currently houses both central identity tables (Users, Passkeys)
  and domain-specific tables (Edge_nodes). According to the spec, subsidiary
  applications should maintain independent databases to prevent schema
  contamination.
- **Attestation Type**: The WebAuthn registration in `core/api-server.ts`
  currently configures `attestationType: "none"`. This deviates from the strict
  hardware attestation and FIDO MDS3 verification required by the target
  architecture.
- **Valkey Bypass**: Current session validation in `core/api-server.ts` queries
  PostgreSQL (`sessions` table) directly instead of utilizing Valkey for
  high-throughput in-memory statefulness.

## 3. Unimplemented Features & Security Gaps

- **Valkey RESP3 Client-Side Caching**: The Valkey integration is missing,
  leaving the system vulnerable to network bottlenecks (the "chatty
  architecture" problem) and lacks microsecond-level session revocation.
- **FIDO MDS3 Attestation Verification**: The system does not currently verify
  hardware provenance against the FIDO Alliance Metadata Service (MDS3),
  allowing software-based passkeys which breaks the strict non-repudiation
  guarantees.
- **RBAC & Multi-tenancy**: The database schema is missing tables for `Apps`,
  `Grants`, and `Invites`. This prevents proper authorization coupling,
  multi-tenant scoping, and invite-code based user provisioning.
- **Internal mTLS**: Communication between the App SDK and the Auth API is not
  yet secured with mTLS (SPIFFE/SPIRE), exposing the internal network to
  sniffing and replay attacks.
- **Network Rate Limiting**: The Auth API lacks multi-layered rate limiting,
  making the (future) Valkey cache vulnerable to exhaustion (OOM) attacks.
- **Monorepo Structure**: The missing root `deno.json` prevents proper monorepo
  workspace management across the decoupled modules.

## 4. Recommended Next Actions

1. **Initialize Monorepo Workspace & Schema Migration**:
   - Create a root `deno.json` to define the workspace (managing `core`,
     `auth-yes`, etc.).
   - Refactor `core/db.ts` to fully align with the isolated identity schema
     (adding `Apps`, `Grants`, `Invites`) and decouple subsidiary app schemas.
2. **Implement Valkey & Client-Side Caching**:
   - Integrate Valkey into the Auth API Gateway for session storage and
     revocation.
   - Implement RESP3 Client-Side Caching in the Deno App SDK
     (`auth-yes/sdk/mod.ts`) to resolve the "chatty architecture" latency and
     enable instant invalidation.
3. **Harden WebAuthn & Internal Networking**:
   - Upgrade the WebAuthn ceremonies to enforce strict hardware attestation
     using FIDO MDS3 BLOB verification.
   - Transition the Auth API and SDK communication from HTTP/REST to gRPC, and
     introduce internal mTLS to secure the zero-trust perimeter.