diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..2726955 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,40 @@ +# Backbone MQTT Broker - AI Agent Documentation + +## Project Overview +Kubernetes-native MQTT broker with JWT authentication and IAM-style access control. Built with TypeScript, Node.js, Fastify, Aedes MQTT broker, Kubernetes client, and Zod validation. + +## Project Structure +- `src/access/` - JWT authentication and IAM-style authorization +- `src/api/` - HTTP API endpoints (Fastify) +- `src/config/` - Environment-based configuration +- `src/k8s/` - Kubernetes operator and CRD management +- `src/server/` - MQTT broker implementation (Aedes) +- `src/topics/` - Topic validation and rules +- `src/utils/` - Service container and shared utilities + +## Code Style Rules +- Always use `.ts` file extensions in imports +- No default exports (use named exports only) +- Use `type` keyword for type definitions (not `interface`) +- Import order: builtin → external → internal → parent → sibling → index +- Add newlines between import groups +- Use path alias `#root/*` for absolute imports from `src/` +- Private class fields use `#` prefix (e.g., `#services`) + +## TypeScript Configuration +- Module system: ESNext with NodeNext resolution +- Strict mode enabled +- Use `.ts` extensions in imports (allowImportingTsExtensions) + +## Available Commands +- `pnpm dev` - Watch mode development +- `pnpm build` - TypeScript compilation +- `pnpm test` - Run all tests (lint + unit) +- `pnpm test:lint` - ESLint check +- `pnpm test:unit` - Vitest unit tests + +## Key Patterns +- Dependency injection via `Services` container class +- Zod schemas for validation +- Environment variables via `Config` class +- Event-driven architecture for K8s resource watching diff --git a/README.md b/README.md new file mode 100644 index 0000000..e7204a8 --- /dev/null +++ b/README.md @@ -0,0 +1,209 @@ +# Backbone + +A Kubernetes-native MQTT broker with fine-grained access control and topic validation. + +## Features + +- **MQTT 3.1.1/5.0 Broker** - Full-featured MQTT broker powered by Aedes +- **Kubernetes Integration** - Custom Resource Definitions (Client, Topic) for declarative configuration +- **JWT-based Authentication** - Pluggable authentication providers with JWT token support +- **Statement-based Authorization** - AWS IAM-style policy statements for fine-grained access control +- **Multiple Transport Protocols** - WebSocket and TCP support for flexible client connections +- **HTTP API** - RESTful API for broker management and monitoring +- **Topic Validation** - Configurable rules for topic structure and content validation + +## Quick Start + +### Using Docker Compose + +1. Clone the repository and start the broker: + +```bash +git clone +cd backbone +docker-compose up -d +``` + +2. The broker will be available on: + - **TCP MQTT**: `tcp://localhost:1883` + - **WebSocket MQTT**: `ws://localhost:8883/ws` + - **HTTP API**: `http://localhost:8883/api` + + +3. Connect with an MQTT client: + +> [!IMPORTANT] +> Connecting requires credentials - documentation is still **TODO** + +```bash +# Using mosquitto_pub +mosquitto_pub -h localhost -p 1883 -t "test/topic" -m "Hello, Backbone!" + +# Using mqtt.js (Node.js) +import mqtt from 'mqtt' +const client = mqtt.connect('ws://localhost:8883/ws') +``` + +## Configuration + +Backbone can be configured using environment variables: + +| Variable | Description | Default | +|----------|-------------|---------| +| `ADMIN_TOKEN` | Admin token for API requests | `undefined` | +| `TOKEN_SECRET` | JWT signing secret for authentication | `undefined` | +| `K8S_ENABLED` | Enable Kubernetes operator mode | `false` | +| `HTTP_ENABLED` | Enable HTTP/WebSocket server | `true` | +| `HTTP_PORT` | HTTP server port | `8883` | +| `TCP_ENABLED` | Enable TCP MQTT server | `true` | +| `TCP_PORT` | TCP server port | `1883` | +| `OIDC_ENABLED` | OIDC discovery URL | `undefined` | +| `OIDC_DISCOVERY` | OIDC discovery URL | `undefined` | +| `OIDC_CLIENT_ID` | OIDC client ID | `undefined` | +| `OIDC_CLIENT_SECRET` | OIDC client secret | `undefined` | +| `OIDC_CLIENT_SECRET` | OIDC client secret | `undefined` | +| `OIDC_GROUP_FIELD` | JWT field for reading groups | `groups` | +| `OIDC_ADMIN_GROUP` | JWT group for admins | `undefined` | +| `OIDC_WRITER_GROUP` | JWT group with publish access to queue | `undefined` | +| `OIDC_READER_GROUP` | JWT group with read-only access to queue | `undefined` | + +### Example Configuration + +```bash +# Basic configuration +export TOKEN_SECRET="your-secret-key" +export HTTP_ENABLED="true" +export TCP_ENABLED="true" + +# Kubernetes mode +export K8S_ENABLED="true" +``` + +## Kubernetes Integration + +Backbone provides Kubernetes Custom Resource Definitions for declarative configuration: + +### Client Resource + +Define MQTT client access policies using the `Client` CRD: + +```yaml +apiVersion: 'backbone.mortenolsen.pro/v1' +kind: Client +metadata: + name: sensor-client + namespace: production +spec: + statements: + - effect: allow + resources: ['sensors/**/data'] + actions: ['mqtt:publish'] + - effect: allow + resources: ['sensors/**/commands'] + actions: ['mqtt:subscribe'] +``` + +### Topic Resource + +Configure topic validation rules: + +```yaml +apiVersion: 'backbone.mortenolsen.pro/v1' +kind: Topic +metadata: + name: sensor-topics + namespace: production +spec: + patterns: + - pattern: 'sensors/**/data' + maxMessageSize: 1024 + allowedQoS: [0, 1] +``` + +The Kubernetes operator automatically watches these resources and applies the access policies and validation rules to the MQTT broker. + +## Authentication & Authorization + +### Authorization Statements + +Access control is defined using statement-based policies similar to AWS IAM: + +```yaml +statements: + - effect: allow # or "deny" + resources: ['*'] # MQTT topic patterns + actions: ['*'] # MQTT actions +``` + +#### MQTT Actions + +- `mqtt:publish` - Permission to publish messages to topics +- `mqtt:subscribe` - Permission to subscribe to topics +- `mqtt:read` - Permission to receive messages from topics + +#### Resource Patterns + +- `*` - All topics +- `sensors/*` - All topics under sensors/ +- `sensors/+/data` - Topics matching the pattern (single-level wildcard) +- `sensors/#` - All topics under sensors/ (multi-level wildcard) + +## API + +### Endpoints + +- **WebSocket MQTT**: `ws://host:8883/ws` +- **TCP MQTT**: `tcp://host:1883` +- **HTTP API**: `http://host:8883/api/*` + +### HTTP API + +The HTTP API provides management endpoints for: +- Client management +- Topic configuration +- Broker statistics +- Health checks + +## Development + +### Prerequisites + +- Node.js 23 or higher +- pnpm package manager + +### Installation + +```bash +# Install dependencies +pnpm install + +# Start development server +pnpm dev + +# Build for production +pnpm build + +# Run tests +pnpm test +``` + +### Project Structure + +``` +src/ +├── access/ # Authentication and authorization +├── api/ # HTTP API endpoints +├── config/ # Configuration management +├── k8s/ # Kubernetes operator and CRDs +├── server/ # MQTT broker implementation +├── topics/ # Topic validation rules +└── utils/ # Shared utilities and services +``` + +## License + +This project is licensed under the GNU General Public License v3.0 (GPL-3.0). + +## Author + +Created by [@morten-olsen](https://github.com/morten-olsen)