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

Junie: security cleanups.

Browse Source
This commit is contained in:
Kyle Isom
2025-06-06 13:50:37 -07:00
parent 95d96732d2
commit 23c7a65799
13 changed files with 812 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/api.md
View File

@@ -12,7 +12,7 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
**Endpoint**: `POST /v1/login/password`
**Description**: Authenticates a user using username and password credentials.
**Description**: Authenticates a user using username and password credentials. This endpoint does not require TOTP verification, even if TOTP is enabled for the user.
**Request Format**:
```json
@@ -34,13 +34,15 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
```json
{
"token": "authentication_token",
"expires": 1621234567
"expires": 1621234567,
"totp_enabled": true
}
```
**Response Fields**:
- `token`: Authentication token to be used for subsequent requests
- `expires`: Unix timestamp when the token expires
- `totp_enabled`: Boolean indicating whether TOTP is enabled for the user
**Error Responses**:
- 400 Bad Request: Invalid request format or missing required fields
@@ -86,6 +88,43 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
- 401 Unauthorized: Invalid or expired token
- 500 Internal Server Error: Server-side error
#### TOTP Verification
**Endpoint**: `POST /v1/login/totp`
**Description**: Verifies a TOTP code for a user and issues a token upon successful verification. This endpoint is used as a separate flow from password authentication.
**Request Format**:
```json
{
"version": "v1",
"username": "username",
"totp_code": "123456"
}
```
**Required Fields**:
- `version`: Must be "v1"
- `username`: Username
- `totp_code`: Time-based One-Time Password code
**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, missing required fields, or TOTP not enabled for user
- 401 Unauthorized: Invalid TOTP code
- 500 Internal Server Error: Server-side error
### Database Credentials
**Endpoint**: `/v1/credentials/database` (Not yet implemented)
@@ -112,14 +151,34 @@ Common HTTP status codes:
## Authentication Flow
### Password Authentication Flow
1. **Initial Authentication**:
- Client sends username and password to `/v1/login/password`
- Server validates credentials and returns a token
- The response includes a `totp_enabled` flag indicating whether TOTP is enabled for the user
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**:
### TOTP Authentication Flow
1. **TOTP Verification** (separate from password authentication):
- Client sends username and TOTP code to `/v1/login/totp`
- Server validates the TOTP code and returns a token if valid
### Token Management
1. **Token Expiration**:
- Tokens expire after 24 hours
- Clients should request a new token before expiration
- Clients should request a new token before expiration
### Multi-Factor Authentication
For users with TOTP enabled, a complete multi-factor authentication flow would involve:
1. Authenticate with username and password using `/v1/login/password`
2. Check the `totp_enabled` flag in the response
3. If TOTP is enabled, prompt the user for their TOTP code
4. Verify the TOTP code using `/v1/login/totp` to get a second token
5. Use either token for subsequent requests (both are valid)

81
docs/api.org
View File

@@ -91,10 +91,74 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
*** Database Credentials
*Endpoint*: =/v1/credentials/database= (Not yet implemented)
*Endpoint*: =GET /v1/database/credentials=
*Description*: Retrieves database credentials for authorized users.
*Request Parameters*:
- =username=: Username of the authenticated user
*Headers*:
- =Authorization=: Bearer token for authentication
*Response Format* (Success - 200 OK):
#+begin_src json
{
"host": "database_host",
"port": 5432,
"name": "database_name",
"user": "database_user",
"password": "database_password"
}
#+end_src
*Error Responses*:
- 400 Bad Request: Invalid request format or missing required parameters
- 401 Unauthorized: Invalid or expired token
- 403 Forbidden: Insufficient permissions to access database credentials
- 500 Internal Server Error: Server-side error
*** TOTP Authentication
*Endpoint*: =POST /v1/login/totp=
*Description*: Authenticates a user using TOTP (Time-based One-Time Password) in addition to username and password.
*Request Format*:
#+begin_src json
{
"version": "v1",
"login": {
"user": "username",
"password": "secret_password",
"totp": "123456"
}
}
#+end_src
*Required Fields*:
- =version=: Must be "v1"
- =login.user=: Username
- =login.password=: User's password
- =login.totp=: 6-digit TOTP code from authenticator app
*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, password, or TOTP code
- 500 Internal Server Error: Server-side error
** Error Handling
All error responses follow a standard format:
@@ -118,11 +182,20 @@ Common HTTP status codes:
1. *Initial Authentication*:
- Client sends username and password to =/v1/login/password=
- Server validates credentials and returns a token
- If TOTP is enabled for the user, authentication with password alone will fail
2. *Subsequent Requests*:
2. *TOTP Authentication*:
- For users with TOTP enabled, client sends username, password, and TOTP code to =/v1/login/totp=
- Server validates all credentials and returns a token
3. *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*:
4. *Token Expiration*:
- Tokens expire after 24 hours
- Clients should request a new token before expiration
- Clients should request a new token before expiration
5. *Database Credential Access*:
- Client sends a GET request to =/v1/database/credentials= with the token in the Authorization header
- Server validates the token and returns the database credentials if the user has sufficient permissions

130
docs/deployment.md Normal file
View File

@@ -0,0 +1,130 @@
# MCIAS Deployment Guide
## Overview
This document provides guidance on deploying the Metacircular Identity and Access System (MCIAS) in a production environment. MCIAS is designed to be deployed behind a reverse proxy that handles TLS termination and security headers.
## Prerequisites
- Linux server with systemd
- Nginx or another reverse proxy for TLS termination
- User and group `mcias` created on the system
- Go 1.23 or later for building from source
## Installation
1. Build the MCIAS binary:
```bash
go build -o mcias ./cmd/mcias
```
2. Create the installation directory:
```bash
sudo mkdir -p /opt/mcias
```
3. Copy the binary and service file:
```bash
sudo cp mcias /opt/mcias/
sudo cp mcias.service /etc/systemd/system/
```
4. Set appropriate permissions:
```bash
sudo chown -R mcias:mcias /opt/mcias
sudo chmod 755 /opt/mcias/mcias
```
5. Initialize the database:
```bash
sudo -u mcias /opt/mcias/mcias init --db /opt/mcias/mcias.db
```
6. Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable mcias
sudo systemctl start mcias
```
## Reverse Proxy Configuration
MCIAS is designed to run behind a reverse proxy that handles TLS termination and security headers. Below is an example Nginx configuration:
```nginx
server {
listen 443 ssl http2;
server_name mcias.example.com;
# SSL configuration
ssl_certificate /etc/letsencrypt/live/mcias.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/mcias.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:50m;
ssl_stapling on;
ssl_stapling_verify on;
# Security headers
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Content-Security-Policy "default-src 'self';" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
# Proxy to MCIAS
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# Redirect HTTP to HTTPS
server {
listen 80;
server_name mcias.example.com;
return 301 https://$host$request_uri;
}
```
## Security Considerations
1. **TLS Configuration**: The reverse proxy should use modern TLS protocols (TLSv1.2 and TLSv1.3) and strong cipher suites.
2. **Security Headers**: The reverse proxy should add security headers to all responses, as shown in the Nginx configuration example.
3. **Firewall Configuration**: Configure your firewall to only allow connections to the MCIAS server from the reverse proxy.
4. **Regular Updates**: Keep the MCIAS software, operating system, and reverse proxy up to date with security patches.
5. **Monitoring**: Set up monitoring for the MCIAS service and review logs regularly for security events.
## Logging
MCIAS logs to the systemd journal by default. You can view logs using:
```bash
sudo journalctl -u mcias
```
Security events are logged with the prefix `SECURITY_EVENT:` and are in JSON format for easy parsing.
## Backup and Recovery
Regularly back up the MCIAS database file (/opt/mcias/mcias.db) to ensure you can recover in case of data loss.
Example backup script:
```bash
#!/bin/bash
BACKUP_DIR="/var/backups/mcias"
TIMESTAMP=$(date +%Y%m%d%H%M%S)
mkdir -p $BACKUP_DIR
sqlite3 /opt/mcias/mcias.db ".backup $BACKUP_DIR/mcias_$TIMESTAMP.db"
```

85
docs/installation.org
View File

@@ -31,7 +31,7 @@ go mod download
MCIAS uses SQLite for data storage. To initialize the database:
#+begin_src bash
go run main.go -init -db ./mcias.db
go run cmd/mcias/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=.
@@ -43,37 +43,76 @@ This command creates a new SQLite database file and initializes it with the sche
To start the MCIAS server with default settings:
#+begin_src bash
go run main.go -db ./mcias.db
go run cmd/mcias/main.go server --db ./mcias.db
#+end_src
By default, the server listens on port 8080.
*** Configuration Options
MCIAS supports the following command-line options:
MCIAS supports the following command-line options for the server:
- =-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
- =--db <path>=: Path to the SQLite database file (default: =mcias.db=)
- =--addr <address>=: Address to listen on (default: =:8080=)
Example with custom port:
#+begin_src bash
go run main.go -db ./mcias.db -addr :9000
go run cmd/mcias/main.go server --db ./mcias.db --addr :9000
#+end_src
** Managing Users and Authentication
*** Adding a New User
To add a new user to the system:
#+begin_src bash
go run cmd/mcias/main.go user add --username <username> --password <password>
#+end_src
*** Managing TOTP Authentication
To enable TOTP for a user:
#+begin_src bash
go run cmd/mcias/main.go totp enable --username <username>
#+end_src
This will generate a TOTP secret for the user and display it. The user should save this secret in their authenticator app.
To add a TOTP token with QR code generation:
#+begin_src bash
go run cmd/mcias/main.go totp add --username <username> --qr-output <path/to/qrcode.png>
#+end_src
To validate a TOTP code:
#+begin_src bash
go run cmd/mcias/main.go totp validate --username <username> --code <totp_code>
#+end_src
** Building from Source
To build a binary:
To build the server binary:
#+begin_src bash
cd cmd/mcias
go build -o mcias
#+end_src
Then run the binary:
#+begin_src bash
./mcias -db ./mcias.db
./mcias server --db ./mcias.db
#+end_src
To build the client binary:
#+begin_src bash
cd cmd/mcias-client
go build -o mcias-client
#+end_src
** Development
@@ -128,6 +167,32 @@ curl -X POST http://localhost:8080/v1/login/token \
}'
#+end_src
*** Authentication with TOTP
To authenticate a user with a password and TOTP code:
#+begin_src bash
curl -X POST http://localhost:8080/v1/login/totp \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"login": {
"user": "username",
"password": "password",
"totp": "123456"
}
}'
#+end_src
*** Retrieving Database Credentials
To retrieve database credentials:
#+begin_src bash
curl -X GET "http://localhost:8080/v1/database/credentials?username=username" \
-H "Authorization: Bearer your_token"
#+end_src
** Troubleshooting
*** Common Issues
@@ -170,4 +235,4 @@ go run main.go -db ./mcias.db > mcias.log 2>&1
3. *User Management*:
- Implement strong password policies
- Regularly rotate tokens
- Monitor for suspicious authentication attempts
- Monitor for suspicious authentication attempts

27
docs/overview.org
View File

@@ -11,10 +11,10 @@ The system currently provides:
1. User password authentication
2. User token authentication
3. Database credential authentication
4. TOTP (Time-based One-Time Password) authentication
Future planned features include:
1. TOTP (Time-based One-Time Password) authentication
2. Policy management for fine-grained access control
1. Policy management for fine-grained access control
** System Architecture
@@ -57,7 +57,8 @@ CREATE TABLE users (
created integer,
user text not null,
password blob not null,
salt blob not null
salt blob not null,
totp_secret text
);
#+end_src
@@ -108,6 +109,24 @@ CREATE TABLE user_roles (
);
#+end_src
*** Permissions Tables
#+begin_src sql
CREATE TABLE permissions (
id TEXT PRIMARY KEY,
resource TEXT NOT NULL,
action TEXT NOT NULL,
description TEXT
);
CREATE TABLE role_permissions (
id TEXT PRIMARY KEY,
rid TEXT NOT NULL,
pid TEXT NOT NULL,
FOREIGN KEY(rid) REFERENCES roles(id),
FOREIGN KEY(pid) REFERENCES permissions(id)
);
#+end_src
** Security Considerations
MCIAS implements several security best practices:
@@ -130,4 +149,4 @@ MCIAS implements several security best practices:
4. *Database Security*
- Parameterized queries to prevent SQL injection
- Foreign key constraints to maintain data integrity
- Foreign key constraints to maintain data integrity