#+title: MCIAS
#+created: <2025-05-09 Fri 13:42>

* MCIAS

  MCIAS is the metacircular identity and access system, providing identity and authentication across metacircular projects.

  It currently provides the following across metacircular services:

  1. User password authentication.
  2. User token authentication.
  3. Database credential authentication.

  Future work should consider adding support for:
  1. TOTP (Time-based One-Time Password)
  2. Policy management for fine-grained access control.

* Documentation

  Comprehensive documentation is available in the [[file:docs/][docs]] directory:

  - [[file:docs/overview.org][Overview]] - Project overview, system architecture, database schema, and security considerations
  - [[file:docs/api.org][API Documentation]] - API endpoints, request/response formats, error handling, and authentication flow
  - [[file:docs/installation.org][Installation and Usage Guide]] - Prerequisites, installation steps, running the server, and more

* Quick Start

  To get started with MCIAS:

  1. Initialize the database:
     #+begin_src bash
     go run main.go init --db ./mcias.db
     #+end_src

  2. Start the server:
     #+begin_src bash
     go run main.go server --db ./mcias.db
     #+end_src

  3. The server will listen on port 8080 by default.

* CLI Commands

  MCIAS provides a command-line interface with the following commands:

** Server Command

   Start the MCIAS server:
   #+begin_src bash
   go run main.go server [--db <path>] [--addr <address>]
   #+end_src

** Init Command

   Initialize the database:
   #+begin_src bash
   go run main.go init [--db <path>]
   #+end_src

** User Commands

   Add a new user:
   #+begin_src bash
   go run main.go user add --username <username> --password <password>
   #+end_src

   List all users:
   #+begin_src bash
   go run main.go user list
   #+end_src

** Token Commands

   Add a new token for a user:
   #+begin_src bash
   go run main.go token add --username <username> [--duration <hours>]
   #+end_src

   List all tokens:
   #+begin_src bash
   go run main.go token list
   #+end_src

* API Overview

** Authentication Endpoints

*** =/v1/login/password=
    Password-based authentication endpoint.

*** =/v1/login/token=
    Token-based authentication endpoint.

*** =/v1/credentials/database=
    Database credential authentication endpoint (not yet fully implemented).

** Request Format

   The general datastructure used to log in should look like:

   #+begin_src json
   {
       "version": "v1",
       "login": {
           "user": "username",
           "password": "secret password",
           "token": "1234567890",
           "totp": "123456"
       }
   }
   #+end_src

   Any fields that aren't used should be omitted. The =version= and
   =login.user= types are required, as well as the appropriate
   credential field.

* Development

  - Run tests: =go test ./...=
  - Run linter: =golangci-lint run=
  - Run specific linter: =golangci-lint run --disable-all --enable=gosec=

  The project uses a strict golangci-lint configuration defined in =.golangci.yml=.
  This configuration includes a comprehensive set of linters focused on:
  - Security best practices
  - Code quality and maintainability
  - Performance considerations
  - Error handling correctness

  See the [[file:docs/installation.org][Installation and Usage Guide]] for more details.