Core implementation written with Junie.

2025-06-06 10:15:49 -07:00
parent 0ef669352f
commit e22c12fd39
28 changed files with 2597 additions and 24 deletions
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -0,0 +1,130 @@
+# 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
+```sql
+CREATE TABLE users (
+       id	text primary key,
+       created	integer,
+       user	text not null,
+       password	blob not null,
+       salt	blob not null
+);
+```
+
+### Tokens Table
+```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)
+);
+```
+
+### Database Credentials Table
+```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
+);
+```
+
+### Registrations Table
+```sql
+CREATE TABLE registrations (
+       id	text primary key,
+       code	text not null
+);
+```
+
+### Roles Tables
+```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)
+);
+```
+
+## 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