Skip to content

README.md

Latest commit

 

History

History
360 lines (255 loc) · 11.4 KB

README.md

File metadata and controls

360 lines (255 loc) · 11.4 KB

Auth Control Console

Auth Control Console is a stateful identity, session, and administrative account governance system for local and containerized engineering workflows. The repository combines a Go API, a React operational console, PostgreSQL-backed persistence, containerized runtime targets, and a security-oriented request pipeline for authentication, session control, recovery flows, audit capture, and user lifecycle administration.

Visual Overview

Session Operations Dashboard

Session Status and Security Controls

Administrative Account Registry

Identity Management and Filtering

Advanced Account Control

Permissions and Administrative Notes

Secure Registration Flow

Password Policy Enforcement

Implemented Capabilities

Auth Control Console currently exposes the following product capabilities:

  • Account registration and interactive sign-in
  • Stateful session issuance, validation, refresh rotation, and revocation
  • Password recovery request and password reset execution
  • Role-based account access with admin and member roles
  • Fine-grained admin permissions for directory, role, session, note, and audit operations
  • Administrative principal directory with search, filtering, sorting, pagination, bulk actions, and export
  • Principal lifecycle operations including status updates, email changes, email verification, reset enforcement, soft delete, and hard delete
  • Per-principal operational notes and permission assignment workflows
  • Authentication telemetry and security event monitoring for sign-in activity

Runtime Topology

Layer Implementation
API runtime Go 1.25, standard library HTTP stack
Web runtime React 18, TypeScript 5, Vite 5
Database PostgreSQL 16
Container web edge Nginx (Docker web image only)
Local orchestration Docker Compose
Security automation GitHub Actions, gosec, govulncheck, Trivy, TruffleHog

Execution Modes

Mode A: Full Docker Runtime

This mode runs PostgreSQL, the Go API, and the web application in containers.

  • postgres runs on the Docker network and is published on 127.0.0.1:15432
  • api runs on the Docker network and is published on 127.0.0.1:18080
  • web runs Nginx on port 80 in-container and is published on 127.0.0.1:15173
  • Browser traffic terminates at Nginx and /api/v1 is proxied to the API container

Relevant files:

Mode B: Hybrid Local Runtime

This mode runs PostgreSQL in Docker while the web application and API run directly on the host machine.

  • PostgreSQL still runs in Docker on 127.0.0.1:15432
  • The API runs locally, typically on 127.0.0.1:18080
  • The web application runs locally through the Vite dev server, typically on 127.0.0.1:15173
  • There is no Nginx hop unless one is introduced explicitly in front of the API

Request Path and Client IP Resolution

Auth Control Console records source telemetry for security events. The API resolves the client IP through a trust-aware forwarding model implemented in middleware.go.

Resolution rules:

  • If the remote peer is not a trusted proxy, the API uses RemoteAddr
  • If the remote peer is a trusted proxy, the API evaluates Forwarded first
  • If Forwarded is unavailable, the API evaluates X-Forwarded-For
  • If the forwarding chain is unavailable, the API falls back to X-Real-IP
  • Only the first non-trusted address found from right to left in the forwarding chain is treated as the client IP

Local Behavior

Hybrid local mode usually produces 127.0.0.1 as the source IP. This is correct because the browser connects directly to the local API process.

Full Docker mode can expose Docker bridge addresses unless the reverse proxy network is explicitly trusted. This repository now configures Docker local proxy trust through:

TRUSTED_PROXY_CIDRS=172.16.0.0/12

This setting is appropriate for the full Docker runtime where Nginx forwards requests to the API over the Docker bridge network. It is not required for hybrid local mode when the browser connects directly to the API.

Security Model

Session Control

  • Sessions are server-side, stateful, and persisted in PostgreSQL
  • Session tokens are generated from cryptographically secure random bytes
  • Stored session records contain token digests rather than raw token values
  • Refresh rotation replaces the active token digest and invalidates the previous credential
  • Session cookies are configured with HttpOnly, SameSite=Strict, and Secure in production contexts
  • Password reset and selected administrative actions revoke active sessions

Credential Handling

  • Password hashes use PBKDF2-HMAC-SHA256
  • Password verification uses constant-time comparison
  • Reset tokens are isolated from session credentials and carry explicit TTL constraints
  • Password policy is validated at the application boundary and surfaced in the UI
  • Password reset enforcement can be toggled per principal by administrators

Request Hardening

  • Same-origin CSRF enforcement is applied to state-changing requests
  • Rate limiting is configurable for global traffic, authentication flows, and recovery flows
  • Security headers include CSP, HSTS, X-Frame-Options, Referrer-Policy, COOP, and CORP
  • Trusted proxy CIDRs control whether forwarding headers are accepted

Audit and Monitoring

  • Structured security events are persisted for audited requests
  • Sign-in telemetry includes outcome, source IP, user agent, account context, and timestamps
  • The monitoring console supports filterable sign-in review across accounts
  • Administrative mutations publish audit metadata for security analysis

User Management Model

Principal States

The user lifecycle model supports the following statuses:

  • active
  • suspended
  • locked
  • pending_verification
  • deleted

Administrative Operations

The directory and admin APIs support the following principal operations:

  • Promote or demote role membership
  • Update account status with an optional reason
  • Revoke all active sessions for a principal
  • Change email and force re-verification semantics
  • Mark email as verified
  • Require password reset on next sign-in
  • Assign or reset fine-grained admin permissions
  • Add operational notes
  • Soft delete or hard delete principals
  • Execute bulk actions across selected principals
  • Export directory data as CSV or JSON

Directory Data Model

The administrative directory exposes the following operational fields:

  • Account identity and email
  • Role and lifecycle status
  • Email verification state
  • Failed login count
  • Risk state
  • Last login timestamp
  • Last password change timestamp
  • Assigned admin permissions
  • Operational note history

Fine-Grained Admin Permissions

The current permission model includes:

  • users.read
  • users.write
  • users.delete
  • roles.write
  • sessions.read
  • sessions.revoke
  • audit.read
  • audit.export
  • notes.read
  • notes.write

Repository Layout

apps/api/   Go API, middleware, domain services, data access, migrations
apps/web/   React UI, routes, pages, styles, shared client logic
.github/    CI workflows and security automation
docs/       Supporting architecture and project documentation

Local Development Prerequisites

  • Go 1.25+
  • Node.js 20+
  • npm 10+
  • Docker and Docker Compose

Bootstrap

1. Install Dependencies

npm run setup

2. Create Runtime Environment Files

Create local runtime environment files from the provided examples before starting the application.

copy apps\api\.env.example apps\api\.env
copy apps\web\.env.example apps\web\.env

On Unix-like shells:

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

These files are required because the runtime reads .env files, not .env.example files.

3. Start the Database Only

npm run db:up

Start Hybrid Local Runtime

npm run dev

This starts the API and web application on the host machine while PostgreSQL remains containerized.

Start Full Docker Runtime

docker compose up --build -d

This starts PostgreSQL, the API, and the Nginx-served web runtime in containers.

Build

npm run build

Test

npm run test

Current scope:

  • npm run test executes the API test suite
  • there is no root-level web test script at this time

Runtime Endpoints

Hybrid Local Runtime

Surface URL
Web application http://127.0.0.1:15173
Dashboard http://127.0.0.1:15173/dashboard
Security monitor http://127.0.0.1:15173/admin/security-monitor
Identity directory http://127.0.0.1:15173/admin/identity
API health path http://127.0.0.1:18080/api/v1/health
API base path http://127.0.0.1:18080/api/v1

Full Docker Runtime

Surface URL
Web application http://127.0.0.1:15173
Dashboard http://127.0.0.1:15173/dashboard
Security monitor http://127.0.0.1:15173/admin/security-monitor
Identity directory http://127.0.0.1:15173/admin/identity
API health path http://127.0.0.1:18080/api/v1/health
API base path http://127.0.0.1:18080/api/v1

Environment Configuration

API

apps/api/.env.example

APP_ENV=development
API_ADDR=127.0.0.1:18080
APP_ORIGIN=http://localhost:15173,http://127.0.0.1:15173
DATABASE_URL=postgres://secure_auth:secure_auth@127.0.0.1:15432/secure_auth?sslmode=disable
SESSION_COOKIE_NAME=sa_session
SESSION_TTL_HOURS=168
RESET_TOKEN_TTL_MINUTES=30
RATE_LIMIT_RPS=0.5
RATE_LIMIT_BURST=8
AUTH_RATE_LIMIT_RPS=0.2
AUTH_RATE_LIMIT_BURST=5
RECOVERY_RATE_LIMIT_RPS=0.1
RECOVERY_RATE_LIMIT_BURST=3
CLEANUP_INTERVAL_MINUTES=15
HSTS_MAX_AGE_SECONDS=31536000
TRUSTED_PROXY_CIDRS=
BOOTSTRAP_ADMIN_EMAIL=
ENABLE_RESET_PREVIEW=false

Recommended values by mode:

  • Hybrid local runtime: TRUSTED_PROXY_CIDRS=
  • Full Docker runtime with bundled Nginx: TRUSTED_PROXY_CIDRS=172.16.0.0/12
  • Production behind reverse proxies: define only the CIDRs owned by the trusted edge or ingress tier

Web

apps/web/.env.example

VITE_API_BASE_URL=http://127.0.0.1:18080/api/v1
VITE_CSP_CONNECT_SRC='self' http://127.0.0.1:18080 ws://127.0.0.1:15173 http://127.0.0.1:15173

Required values by mode:

  • Hybrid local runtime: VITE_API_BASE_URL=http://127.0.0.1:18080/api/v1
  • Full Docker runtime: the Docker build passes VITE_API_BASE_URL=/api/v1

Docker Compose Notes

The Docker web image includes Nginx and forwards API requests through /api/v1.

Relevant forwarding headers configured in apps/web/nginx.conf:

  • X-Real-IP
  • X-Forwarded-For
  • X-Forwarded-Proto

The full Docker runtime now trusts the Docker bridge CIDR in docker-compose.yml so that security telemetry can resolve the browser client address instead of the Nginx container address.

Administrative Role Operations

Administrative role changes can also be executed through the API runtime process:

docker compose exec api /app/server -promote principal@example.com
docker compose exec api /app/server -demote principal@example.com

Product Naming

  • Product name: Auth Control Console
  • Repository and service identifiers may still use secure-auth-api where technical naming stability is required