#Authentication

Firmiana uses opaque database-backed bearer tokens for Matrix session management, not pure JWTs.

#Token Types

#Auth Flow

#Registration (UIAA)

Client → POST /register → { flows: [{stages: ["m.login.dummy"]}] }
Client → POST /register → { auth: {type: "m.login.dummy", session: "..."} }
Server → 200 OK → { user_id, access_token, device_id }

Registration uses the UIAA (User-Interactive Authentication API) framework. The server declares available authentication flows, and the client completes each stage.

Supported stages:

• m.login.password — Username/password authentication
• m.login.dummy — No-op stage (for registration without password)

#Login

Client → POST /login → { type: "m.login.password", identifier: {type: "m.id.user", user: "alice"}, password: "secret" }
Server → 200 OK → { user_id, access_token, device_id, home_server }

Login creates a new device entry and issues an access token + refresh token pair.

#Token Refresh

Client → POST /token/refresh → { access_token, refresh_token }
Server → 200 OK → { access_token, refresh_token }

#Logout

Client → POST /logout → (revoke current device token)
Client → POST /logout/all → (revoke all device tokens)

#Token Validation

Every authenticated request goes through:

1. MatrixAccessTokenValidator.validateToken() — Extracts Bearer <token> from Authorization header
2. MatrixTokenService.validateAccessToken() — Looks up token in user_access_tokens table
3. Token metadata loaded into Authentication attributes:
   • user_id — Matrix user ID
   • device_id — Device identifier
   • access_token_id — Database record ID
   • is_guest — Guest flag
   • is_admin — Admin flag

#Password Storage

Passwords are hashed using PBKDF2 with SHA-256. The system supports automatic upgrade of legacy hash formats when a user successfully logs in.

#Configuration

micronaut:
  security:
    enabled: true
    authentication: bearer
    token:
      name: Authorization
      jwt:
        enabled: true          # Note: JWT config is present but Matrix auth uses opaque tokens
        signatures:
          secret:
            default:
              secret: ${JWT_SECRET:...}