kyle/mcias
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Core implementation written with Junie.

Browse Source
This commit is contained in:
Kyle Isom
2025-06-06 10:15:49 -07:00
parent 0ef669352f
commit e22c12fd39
28 changed files with 2597 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/README.md Normal file
View File

@@ -0,0 +1,43 @@
# MCIAS Documentation
Welcome to the MCIAS (Metacircular Identity and Access System) documentation. This directory contains comprehensive documentation for understanding, installing, and using the MCIAS system.
## Documentation Index
### [Overview](overview.md)
- Project overview
- System architecture
- Database schema
- Security considerations
### [API Documentation](api.md)
- API endpoints
- Request/response formats
- Error handling
- Authentication flow
### [Installation and Usage Guide](installation.md)
- Prerequisites
- Installation steps
- Running the server
- Configuration options
- Building from source
- Development practices
- API usage examples
- Troubleshooting
- Security best practices
## Additional Resources
- [Project Repository](https://git.wntrmute.dev/kyle/mcias)
- [Schema File](../schema.sql) - Database schema definition
## Contributing to Documentation
When contributing to this documentation, please follow these guidelines:
1. Use Markdown format for all documentation files
2. Keep the documentation up-to-date with code changes
3. Include examples where appropriate
4. Organize content logically with clear headings
5. Use code blocks with syntax highlighting for code examples

46
docs/README.org Normal file
View File

@@ -0,0 +1,46 @@
#+title: MCIAS Documentation
#+created: <2025-05-09 Fri 13:42>
* MCIAS Documentation
Welcome to the MCIAS (Metacircular Identity and Access System) documentation. This directory contains comprehensive documentation for understanding, installing, and using the MCIAS system.
* Documentation Index
** [[file:overview.org][Overview]]
- Project overview
- System architecture
- Database schema
- Security considerations
** [[file:api.org][API Documentation]]
- API endpoints
- Request/response formats
- Error handling
- Authentication flow
** [[file:installation.org][Installation and Usage Guide]]
- Prerequisites
- Installation steps
- Running the server
- Configuration options
- Building from source
- Development practices
- API usage examples
- Troubleshooting
- Security best practices
* Additional Resources
- [[https://git.wntrmute.dev/kyle/mcias][Project Repository]]
- [[file:../schema.sql][Schema File]] - Database schema definition
* Contributing to Documentation
When contributing to this documentation, please follow these guidelines:
1. Use org-mode format for all documentation files
2. Keep the documentation up-to-date with code changes
3. Include examples where appropriate
4. Organize content logically with clear headings
5. Use code blocks with syntax highlighting for code examples

125
docs/api.md Normal file
View File

@@ -0,0 +1,125 @@
# MCIAS API Documentation
## Overview
MCIAS (Metacircular Identity and Access System) provides identity and authentication services across metacircular projects. This document describes the REST API endpoints, request/response formats, and error handling.
## API Endpoints
### Authentication
#### Password-based Authentication
**Endpoint**: `POST /v1/login/password`
**Description**: Authenticates a user using username and password credentials.
**Request Format**:
```json
{
"version": "v1",
"login": {
"user": "username",
"password": "secret_password"
}
}
```
**Required Fields**:
- `version`: Must be "v1"
- `login.user`: Username
- `login.password`: User's password
**Response Format** (Success - 200 OK):
```json
{
"token": "authentication_token",
"expires": 1621234567
}
```
**Response Fields**:
- `token`: Authentication token to be used for subsequent requests
- `expires`: Unix timestamp when the token expires
**Error Responses**:
- 400 Bad Request: Invalid request format or missing required fields
- 401 Unauthorized: Invalid username or password
- 500 Internal Server Error: Server-side error
#### Token-based Authentication
**Endpoint**: `POST /v1/login/token`
**Description**: Authenticates a user using a previously issued token.
**Request Format**:
```json
{
"version": "v1",
"login": {
"user": "username",
"token": "existing_token"
}
}
```
**Required Fields**:
- `version`: Must be "v1"
- `login.user`: Username
- `login.token`: Previously issued authentication token
**Response Format** (Success - 200 OK):
```json
{
"token": "new_authentication_token",
"expires": 1621234567
}
```
**Response Fields**:
- `token`: New authentication token to be used for subsequent requests
- `expires`: Unix timestamp when the token expires
**Error Responses**:
- 400 Bad Request: Invalid request format or missing required fields
- 401 Unauthorized: Invalid or expired token
- 500 Internal Server Error: Server-side error
### Database Credentials
**Endpoint**: `/v1/credentials/database` (Not yet implemented)
**Description**: Retrieves database credentials for authorized users.
## Error Handling
All error responses follow a standard format:
```json
{
"error": "Error message describing the issue"
}
```
Common HTTP status codes:
- 200 OK: Request successful
- 400 Bad Request: Invalid request format or parameters
- 401 Unauthorized: Authentication failed
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource not found
- 500 Internal Server Error: Server-side error
## Authentication Flow
1. **Initial Authentication**:
- Client sends username and password to `/v1/login/password`
- Server validates credentials and returns a token
2. **Subsequent Requests**:
- Client uses the token for authentication by sending it to `/v1/login/token`
- Server validates the token and issues a new token
3. **Token Expiration**:
- Tokens expire after 24 hours
- Clients should request a new token before expiration

128
docs/api.org Normal file
View File

@@ -0,0 +1,128 @@
#+title: MCIAS API Documentation
#+created: <2025-05-09 Fri 13:42>
* MCIAS API Documentation
** Overview
MCIAS (Metacircular Identity and Access System) provides identity and authentication services across metacircular projects. This document describes the REST API endpoints, request/response formats, and error handling.
** API Endpoints
*** Authentication
**** Password-based Authentication
*Endpoint*: =POST /v1/login/password=
*Description*: Authenticates a user using username and password credentials.
*Request Format*:
#+begin_src json
{
"version": "v1",
"login": {
"user": "username",
"password": "secret_password"
}
}
#+end_src
*Required Fields*:
- =version=: Must be "v1"
- =login.user=: Username
- =login.password=: User's password
*Response Format* (Success - 200 OK):
#+begin_src json
{
"token": "authentication_token",
"expires": 1621234567
}
#+end_src
*Response Fields*:
- =token=: Authentication token to be used for subsequent requests
- =expires=: Unix timestamp when the token expires
*Error Responses*:
- 400 Bad Request: Invalid request format or missing required fields
- 401 Unauthorized: Invalid username or password
- 500 Internal Server Error: Server-side error
**** Token-based Authentication
*Endpoint*: =POST /v1/login/token=
*Description*: Authenticates a user using a previously issued token.
*Request Format*:
#+begin_src json
{
"version": "v1",
"login": {
"user": "username",
"token": "existing_token"
}
}
#+end_src
*Required Fields*:
- =version=: Must be "v1"
- =login.user=: Username
- =login.token=: Previously issued authentication token
*Response Format* (Success - 200 OK):
#+begin_src json
{
"token": "new_authentication_token",
"expires": 1621234567
}
#+end_src
*Response Fields*:
- =token=: New authentication token to be used for subsequent requests
- =expires=: Unix timestamp when the token expires
*Error Responses*:
- 400 Bad Request: Invalid request format or missing required fields
- 401 Unauthorized: Invalid or expired token
- 500 Internal Server Error: Server-side error
*** Database Credentials
*Endpoint*: =/v1/credentials/database= (Not yet implemented)
*Description*: Retrieves database credentials for authorized users.
** Error Handling
All error responses follow a standard format:
#+begin_src json
{
"error": "Error message describing the issue"
}
#+end_src
Common HTTP status codes:
- 200 OK: Request successful
- 400 Bad Request: Invalid request format or parameters
- 401 Unauthorized: Authentication failed
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource not found
- 500 Internal Server Error: Server-side error
** Authentication Flow
1. *Initial Authentication*:
- Client sends username and password to =/v1/login/password=
- Server validates credentials and returns a token
2. *Subsequent Requests*:
- Client uses the token for authentication by sending it to =/v1/login/token=
- Server validates the token and issues a new token
3. *Token Expiration*:
- Tokens expire after 24 hours
- Clients should request a new token before expiration

170
docs/installation.md Normal file
View File

@@ -0,0 +1,170 @@
# MCIAS Installation and Usage Guide
## Prerequisites
Before installing MCIAS, ensure you have the following prerequisites:
- Go 1.23 or later
- SQLite3
- golangci-lint (for development)
## Installation
### Clone the Repository
```bash
git clone git.wntrmute.dev/kyle/mcias
cd mcias
```
### Install Dependencies
```bash
go mod download
```
### Initialize the Database
MCIAS uses SQLite for data storage. To initialize the database:
```bash
go run main.go -init -db ./mcias.db
```
This command creates a new SQLite database file and initializes it with the schema defined in `schema.sql`.
## Running the Server
### Basic Usage
To start the MCIAS server with default settings:
```bash
go run main.go -db ./mcias.db
```
By default, the server listens on port 8080.
### Configuration Options
MCIAS supports the following command-line options:
- `-db <path>`: Path to the SQLite database file (default: `mcias.db`)
- `-addr <address>`: Address to listen on (default: `:8080`)
- `-init`: Initialize the database and exit
Example with custom port:
```bash
go run main.go -db ./mcias.db -addr :9000
```
## Building from Source
To build a binary:
```bash
go build -o mcias
```
Then run the binary:
```bash
./mcias -db ./mcias.db
```
## Development
### Running Tests
To run all tests:
```bash
go test ./...
```
### Linting
To run the linter:
```bash
golangci-lint run
```
## Using the API
### Authentication with Password
To authenticate a user with a password:
```bash
curl -X POST http://localhost:8080/v1/login/password \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"login": {
"user": "username",
"password": "password"
}
}'
```
### Authentication with Token
To authenticate a user with a token:
```bash
curl -X POST http://localhost:8080/v1/login/token \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"login": {
"user": "username",
"token": "your_token"
}
}'
```
## Troubleshooting
### Common Issues
1. **Database errors**: Ensure the database file exists and has the correct permissions.
```bash
# Check permissions
ls -l mcias.db
# Fix permissions if needed
chmod 644 mcias.db
```
2. **Port already in use**: If the port is already in use, specify a different port with the `-addr` flag.
```bash
go run main.go -db ./mcias.db -addr :8081
```
3. **Authentication failures**: Ensure you're using the correct username and password/token.
### Logging
MCIAS logs to stdout by default. To capture logs to a file:
```bash
go run main.go -db ./mcias.db > mcias.log 2>&1
```
## Security Best Practices
1. **Production Deployment**:
- Use HTTPS in production
- Set up proper firewall rules
- Run the service with minimal privileges
2. **Database Security**:
- Regularly backup the database
- Restrict file permissions on the database file
- Consider encrypting the database file at rest
3. **User Management**:
- Implement strong password policies
- Regularly rotate tokens
- Monitor for suspicious authentication attempts

173
docs/installation.org Normal file
View File

@@ -0,0 +1,173 @@
#+title: MCIAS Installation and Usage Guide
#+created: <2025-05-09 Fri 13:42>
* MCIAS Installation and Usage Guide
** Prerequisites
Before installing MCIAS, ensure you have the following prerequisites:
- Go 1.23 or later
- SQLite3
- golangci-lint (for development)
** Installation
*** Clone the Repository
#+begin_src bash
git clone git.wntrmute.dev/kyle/mcias
cd mcias
#+end_src
*** Install Dependencies
#+begin_src bash
go mod download
#+end_src
*** Initialize the Database
MCIAS uses SQLite for data storage. To initialize the database:
#+begin_src bash
go run main.go -init -db ./mcias.db
#+end_src
This command creates a new SQLite database file and initializes it with the schema defined in =schema.sql=.
** Running the Server
*** Basic Usage
To start the MCIAS server with default settings:
#+begin_src bash
go run main.go -db ./mcias.db
#+end_src
By default, the server listens on port 8080.
*** Configuration Options
MCIAS supports the following command-line options:
- =-db <path>=: Path to the SQLite database file (default: =mcias.db=)
- =-addr <address>=: Address to listen on (default: =:8080=)
- =-init=: Initialize the database and exit
Example with custom port:
#+begin_src bash
go run main.go -db ./mcias.db -addr :9000
#+end_src
** Building from Source
To build a binary:
#+begin_src bash
go build -o mcias
#+end_src
Then run the binary:
#+begin_src bash
./mcias -db ./mcias.db
#+end_src
** Development
*** Running Tests
To run all tests:
#+begin_src bash
go test ./...
#+end_src
*** Linting
To run the linter:
#+begin_src bash
golangci-lint run
#+end_src
** Using the API
*** Authentication with Password
To authenticate a user with a password:
#+begin_src bash
curl -X POST http://localhost:8080/v1/login/password \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"login": {
"user": "username",
"password": "password"
}
}'
#+end_src
*** Authentication with Token
To authenticate a user with a token:
#+begin_src bash
curl -X POST http://localhost:8080/v1/login/token \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"login": {
"user": "username",
"token": "your_token"
}
}'
#+end_src
** Troubleshooting
*** Common Issues
1. *Database errors*: Ensure the database file exists and has the correct permissions.
#+begin_src bash
# Check permissions
ls -l mcias.db
# Fix permissions if needed
chmod 644 mcias.db
#+end_src
2. *Port already in use*: If the port is already in use, specify a different port with the =-addr= flag.
#+begin_src bash
go run main.go -db ./mcias.db -addr :8081
#+end_src
3. *Authentication failures*: Ensure you're using the correct username and password/token.
*** Logging
MCIAS logs to stdout by default. To capture logs to a file:
#+begin_src bash
go run main.go -db ./mcias.db > mcias.log 2>&1
#+end_src
** Security Best Practices
1. *Production Deployment*:
- Use HTTPS in production
- Set up proper firewall rules
- Run the service with minimal privileges
2. *Database Security*:
- Regularly backup the database
- Restrict file permissions on the database file
- Consider encrypting the database file at rest
3. *User Management*:
- Implement strong password policies
- Regularly rotate tokens
- Monitor for suspicious authentication attempts

130
docs/overview.md Normal file
View File

@@ -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

133
docs/overview.org Normal file
View File

@@ -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