Core implementation written with Junie.

docs/overview.org

@@ -0,0 +1,133 @@
+#+title: MCIAS: Metacircular Identity and Access System
+#+created: <2025-05-09 Fri 13:42>
+
+* MCIAS: Metacircular Identity and Access System
+
+** Project Overview
+
+MCIAS (Metacircular Identity and Access System) is a centralized identity and access management system designed to provide authentication and authorization services across metacircular projects. It serves as a single source of truth for user identity and access control.
+
+The system currently provides:
+1. User password authentication
+2. User token authentication
+3. Database credential authentication
+
+Future planned features include:
+1. TOTP (Time-based One-Time Password) authentication
+2. Policy management for fine-grained access control
+
+** System Architecture
+
+MCIAS is built as a standalone REST API service with the following components:
+
+*** Core Components
+
+1. *API Layer* (=api/= directory)
+   - HTTP server and routing
+   - Request/response handling
+   - Authentication endpoints
+   - Error handling
+
+2. *Data Layer* (=data/= directory)
+   - User management
+   - Token management
+   - Password hashing and verification
+   - Secure random generation
+
+3. *Database* (SQLite)
+   - Persistent storage for users, tokens, and credentials
+   - Schema defined in =schema.sql=
+
+*** Request Flow
+
+1. Client sends authentication request to the API
+2. API layer validates the request format
+3. Data layer processes the authentication logic
+4. Database is queried to verify credentials
+5. Response is generated and sent back to the client
+
+** Database Schema
+
+MCIAS uses a SQLite database with the following tables:
+
+*** Users Table
+#+begin_src sql
+CREATE TABLE users (
+       id	text primary key,
+       created	integer,
+       user	text not null,
+       password	blob not null,
+       salt	blob not null
+);
+#+end_src
+
+*** Tokens Table
+#+begin_src sql
+CREATE TABLE tokens (
+       id	text primary key,
+       uid	text not null,
+       token	text not null,
+       expires	integer default 0,
+       FOREIGN KEY(uid) REFERENCES user(id)
+);
+#+end_src
+
+*** Database Credentials Table
+#+begin_src sql
+CREATE TABLE database (
+       id	text primary key,
+       host	text not null,
+       port	integer default 5432,
+       name	text not null,
+       user	text not null,
+       password	text not null
+);
+#+end_src
+
+*** Registrations Table
+#+begin_src sql
+CREATE TABLE registrations (
+       id	text primary key,
+       code	text not null
+);
+#+end_src
+
+*** Roles Tables
+#+begin_src sql
+CREATE TABLE roles (
+       id	text primary key,
+       role	text not null
+);
+
+CREATE TABLE user_roles (
+	id	text primary key,
+	uid	text not null,
+	rid	text not null,
+	FOREIGN KEY(uid) REFERENCES user(id),
+	FOREIGN KEY(rid) REFERENCES roles(id)
+);
+#+end_src
+
+** Security Considerations
+
+MCIAS implements several security best practices:
+
+1. *Password Security*
+   - Passwords are never stored in plaintext
+   - Scrypt key derivation function is used for password hashing
+   - Each user has a unique random salt
+   - Constant-time comparison is used to prevent timing attacks
+
+2. *Token Security*
+   - Tokens are generated using cryptographically secure random functions
+   - Tokens have an expiration time (24 hours by default)
+   - New tokens are issued on each successful authentication
+
+3. *API Security*
+   - Input validation on all endpoints
+   - Standardized error responses that don't leak sensitive information
+   - Rate limiting (to be implemented)
+
+4. *Database Security*
+   - Parameterized queries to prevent SQL injection
+   - Foreign key constraints to maintain data integrity