System Overview

High-Level Architecture

Kyqu is an authentication control plane with two main runtime components and a client SDK:

┌─────────────────────────────────────────────────────────────────┐
│                  Admin Dashboard (React SPA)                     │
│                    Served via reverse proxy                      │
└────────────────────────┬────────────────────────────────────────┘
                         │ XHR + credentials: "include"
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Auth API Server (Node HTTP)                    │
│                         Internal port                            │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  Router                                                      │ │
│  │  ├── /api/admin/*  → AdminSession + CSRF                    │ │
│  │  └── /api/projects/*/auth/*  → PublicKey authentication     │ │
│  └──────────────────────┬──────────────────────────────────────┘ │
│                          │                                         │
│  ┌──────────────────────▼───────────────────────────────────────┐ │
│  │  Platform Service                                            │ │
│  │  signup, login, sessions, webhooks, email, TOTP, OAuth,     │ │
│  │  WebAuthn, superadmin, audit logs, templates                 │ │
│  └──────────────────────┬───────────────────────────────────────┘ │
│                          │                                         │
│  ┌──────────────────────▼───────────────────────────────────────┐ │
│  │  Database Layer                                              │ │
│  │  PostgreSQL pool, auto-migration, 34 tables                  │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌────────────┐  ┌──────────┐  ┌────────────┐  ┌──────────────┐ │
│  │ Email (SMTP)│  │ Rate     │  │ CSRF       │  │ Monitoring   │ │
│  │ Raw TCP/TLS│  │ Limiting │  │ Double-    │  │ Webhook      │ │
│  │            │  │ Mem/PG   │  │ Submit     │  │ Alerts       │ │
│  └────────────┘  └──────────┘  └────────────┘  └──────────────┘ │
└──────────────────────────────────────────────────────────────────┘
                         │
                         ▼ PostgreSQL

Admin vs. Project User Separation

Kyqu has two completely separate user models:

Admin Users (admin_users table)

• Manage projects, settings, webhooks, email templates
• Authenticated via HttpOnly cookies + CSRF double-submit tokens
• Signed in from the admin dashboard
• Session stored in admin_sessions table

Project Users (project_users table)

• End users of your integrated products
• Authenticated via bearer tokens (returned to the integrating app)
• Each project has its own isolated user base
• Session stored in project_sessions table

This separation means:

• Admin credentials never leak to project users
• Project user sessions are opaque bearer tokens, not cookies
• Each project's user data is scoped by project_id

Key Design Decisions

Decision	Rationale
Zero-dependency security	scrypt, TOTP, CSRF, SMTP all built from scratch
PostgreSQL	Production-grade persistence
Double-submit CSRF	Non-HttpOnly cookie + header comparison with timingSafeEqual
Idempotent migrations	Schema auto-applied on every startup