mcias/README.org

#+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.
  4. TOTP (Time-based One-Time Password) authentication.

  Future work should consider adding support for:
  1. 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 cmd/mcias/main.go init --db ./mcias.db
     #+end_src

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

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

* CLI Commands

  MCIAS provides two command-line interfaces:

  1. The server CLI (`mcias`) for managing the MCIAS server
  2. The client CLI (`mcias-client`) for interacting with the MCIAS server

** Server CLI Commands

** Server Command

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

** Init Command

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

** User Commands

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

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

** Token Commands

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

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

** TOTP Commands

   Enable TOTP for a user:
   #+begin_src bash
   go run cmd/mcias/main.go totp enable --username <username>
   #+end_src

   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> [--issuer <issuer>]
   #+end_src

   Validate a TOTP code:
   #+begin_src bash
   go run cmd/mcias/main.go totp validate --username <username> --code <totp_code>
   #+end_src

** Migrate Commands

   Apply database migrations:
   #+begin_src bash
   go run cmd/mcias/main.go migrate up [--migrations <dir>] [--steps <n>]
   #+end_src

   Revert database migrations:
   #+begin_src bash
   go run cmd/mcias/main.go migrate down [--migrations <dir>] [--steps <n>]
   #+end_src

   Show current migration version:
   #+begin_src bash
   go run cmd/mcias/main.go migrate version [--migrations <dir>]
   #+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.

* Client Tool

  MCIAS includes a separate command-line client tool (`mcias-client`) that can be used to interact with the MCIAS server. The client tool provides access to all the APIs defined in the server.

** Installation

   To build and install the client tool:

   #+begin_src bash
   cd cmd/mcias-client
   go build -o mcias-client
   # Optional: Move to a directory in your PATH
   sudo mv mcias-client /usr/local/bin/
   #+end_src

** Client CLI Commands

*** Login Commands

    Login with username and password:
    #+begin_src bash
    mcias-client login password --username <username> --password <password> [--totp <code>]
    #+end_src

    Login with a token:
    #+begin_src bash
    mcias-client login token --username <username> --token <token>
    #+end_src

*** Database Commands

    Get database credentials:
    #+begin_src bash
    mcias-client database credentials --username <username> --token <token>
    #+end_src

    Or use a stored token from a previous login:
    #+begin_src bash
    mcias-client database credentials --use-stored
    #+end_src

** Configuration

   The client tool can be configured using command-line flags or a configuration file:

   - `--server`: MCIAS server address (default: http://localhost:8080)
   - `--token-file`: File to store authentication token (default: $HOME/.mcias-token)
   - `--config`: Config file (default: $HOME/.mcias-client.yaml)

   Example configuration file ($HOME/.mcias-client.yaml):
   #+begin_src yaml
   server: "http://mcias.example.com:8080"
   token-file: "/path/to/token/file"
   #+end_src