mcias/docs/overview.md

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

CREATE TABLE users (
       id	text primary key,
       created	integer,
       user	text not null,
       password	blob not null,
       salt	blob not null
);

Tokens Table

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

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

CREATE TABLE registrations (
       id	text primary key,
       code	text not null
);

Roles Tables

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