README.md

OddNet Matrix Controller

A Matrix bot with PostgreSQL-backed user management and role-based command authorization.

Features

• 🔐 PostgreSQL-backed user management - Store user data and roles in a relational database
• 🛡️ Role-based access control - Restrict commands to users with specific roles
• 📊 Entity-based architecture - TypeORM entities that reflect database tables
• 🔄 Database migrations - Version-controlled schema changes
• ⚙️ Environment-based configuration - Easy setup with .env files

Prerequisites

• Node.js 18 or higher
• PostgreSQL server (local or remote)
• Matrix account with access token

Quick Start

1. Install Dependencies

npm install

2. Configure Environment

Copy the example environment file and update it with your credentials:

cp .env.example .env

Edit .env with your Matrix and PostgreSQL credentials:

# Matrix Configuration
MATRIX_SERVER=https://matrix.example.com
MANAGER_MATRIX_ID=@bot:example.com
MANAGER_MATRIX_ACCESS_TOKEN=your_access_token_here

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_db_password
DB_NAME=oddnet_matrix

3. Set Up Database

Create the database (if it doesn't exist):

CREATE DATABASE oddnet_matrix;

Run migrations to create tables:

npm run migration:run

4. Add Your First Admin User

Edit scripts/setup-db.sql with your Matrix ID and run:

psql -U postgres -f scripts/setup-db.sql

Or manually insert into your database:

\c oddnet_matrix

INSERT INTO users ("matrixId", "displayName", "isActive") 
VALUES ('@yourname:matrix.org', 'Your Name', true);

INSERT INTO user_roles ("matrixId", "roleId") 
VALUES ('@yourname:matrix.org', 1);  -- 1 = admin role

5. Run the Bot

Development mode (with hot reload):

npm run dev

Production mode:

npm run build
npm start

Database Management

See DATABASE.md for comprehensive documentation on:

• Database schema and entity relationships
• Migration commands and workflow
• User and role management
• Creating custom roles
• Programmatic database access

Available Commands

• !ping - Check if the bot is responsive (public)
• !echo <message> - Echo back a message (requires: user, admin)
• !admin users - List all registered users (requires: admin)
• !admin roles - List all available roles (requires: admin)
• !help - Show help message (public)

Project Structure

src/
├── controllers/
│   ├── CommandController.ts      # Command routing and authorization
│   ├── InputController.ts        # Message handling
│   └── commands/                 # Individual command handlers
│       ├── pingCommand.ts
│       ├── echoCommand.ts
│       ├── helpCommand.ts
│       └── adminCommand.ts
├── database/
│   ├── entities/                 # TypeORM entities
│   │   ├── User.ts
│   │   ├── Role.ts
│   │   └── UserRole.ts
│   ├── migrations/               # Database migrations
│   ├── dataSource.ts             # TypeORM configuration
│   └── DatabaseService.ts        # Database service layer
├── middleware/
│   └── AuthorizationMiddleware.ts # Role-based access control
├── services/
│   └── MatrixService.ts          # Matrix SDK wrapper
├── types/
│   ├── CommandTypes.ts           # Command type definitions
│   └── Message.ts                # Message type definitions
└── main.ts                       # Application entry point

Creating New Commands

To create a new command with role-based access:

1. Create a command handler in src/controllers/commands/:

import { MatrixService } from '../../services/MatrixService';
import { GeneralMessage } from '../../types/Message';
import { DatabaseService } from '../../database/DatabaseService';

export async function handleMyCommand(
  message: GeneralMessage,
  args: string[],
  matrixService: MatrixService,
  databaseService: DatabaseService
): Promise<void> {
  // Your command logic here
  await matrixService.sendMessage(message.roomId, 'Response');
}

2. Register it in CommandController.ts:

this.commands.set('mycommand', { 
  handler: handleMyCommand,
  requiredRoles: ['user', 'admin'],  // Optional
  description: 'My command description'
});

Default Roles

Three roles are created by the initial migration:

• admin - Full access to all commands
• user - Basic access to user-level commands
• moderator - Elevated permissions for moderation

You can create custom roles through SQL or by extending the admin commands.

License

Apache-2.0