Skip to content
pasztor-markPublic

About

a free, open-source chat layer you embed in your own application. Your app handles its users and signs the JWTs, dotwire handles the rest

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

dotwire

Self-hosted alternative to Stream and Sendbird: no per-MAU bill and no second user table.

.NET 10 TimescaleDB NATS JetStream Encryption License

dotwire is a free, open-source chat layer you embed in your own application. Your app keeps owning its users and signs the JWTs; dotwire verifies them and handles realtime delivery, message persistence and ordering, and a tamper-evident audit log. It ships APIs and SDKs, not a chat UI, so you build the interface your product needs.

Early release (v0.4). APIs and deployment guidance may still change, and dotwire isn't used in production yet, so evaluate it carefully before relying on it. Feedback and issues are welcome.


Key Highlights

  • Native AOT: Compiled ahead-of-time with .NET 10 Native AOT into a standalone binary.
  • Stateless Host-Owned Identity: Authenticates via host-signed RS256 JWTs with authoritative database role cross-checks. dotwire owns zero user tables.
  • Decoupled Persistence Pipeline: Client send acknowledgements (202 Accepted) confirm NATS JetStream persistence, independently of background TimescaleDB batch ingestion.
  • Shard-Key Discipline: Hot-path queries include room_id; TimescaleDB hypertables support time-based retention through chunk drops.
  • Envelope Encryption at Rest: Payloads are encrypted with AES-256-GCM (nonce(12) ‖ ciphertext ‖ tag(16)) at the gateway before publishing to JetStream or writing to disk. Key IDs travel alongside envelopes for zero-downtime key rotation.
  • Tamper-Evident Audit Chain: Append-only compliance log hash-chained with SHA-256, anchored by periodic checkpoints, verifiable via GET /audit/verify, and protected with database-level revoked grants and guard triggers.
  • Compliance Surface: Redaction, DSAR export, and configurable retention (Postgres chunk drops + JetStream MaxAge) via the admin API and both host SDKs.
  • Webhooks & SSE: Optional presend/postsend webhook call-outs for host-side moderation, and a resumable Server-Sent Events read path alongside SignalR.
  • Per-Node Rate Limiting: In-process token-bucket limits on send, read, admin, and hub routes — no external dependency.

Architecture Overview

                      ┌────────────────────────────────────────────────────────┐
                      │              HOST CLIENT / WEB FRONTEND                │
                      └────────────────────────────────────────────────────────┘
                                                   │
                            POST /rooms/{roomId}/messages (RS256 JWT)
                                                   ▼
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│ dotwire Gateway Node (.NET 10 Native AOT)                                                    │
│                                                                                              │
│  1. JwtBearer: Validate RS256 Signature + Exp + Claims                                       │
│  2. RoomAccessFilter: role + membership in one query (Read Pool)                             │
│  3. MessageCipher: Encrypt Payload (AES-256-GCM under active key)                            │
│  4. JetStream Publish: Publish to NATS stream ROOMS (subject: room.{roomId})                  │
│  5. Client Ack: Return HTTP 202 Accepted with (seq, time)                                    │
└──────────────────────────────────────────────────────────────────────────────────────────────┘
                                                   │
                        JetStream Ingest (TCP)     │     Background Batch Insert
                                                   ▼
             ┌──────────────────────────┐     ┌──────────────────────────┐
             │    NATS JetStream 2.10   │ ──► │  PostgresWriterService   │
             │   (File-Backed Storage)  │     │   (≤ 500 msgs / 1s batch)│
             └──────────────────────────┘     └──────────────────────────┘
                                                           │
                                                           ▼
                                              ┌──────────────────────────┐
                                              │   TimescaleDB (Postgres) │
                                              │  (messages Hypertable)   │
                                              └──────────────────────────┘

Quickstart (Docker Compose)

1. Prerequisites

  • Docker & Docker Compose
  • OpenSSL (for generating test keys)

2. Configure Environment

# Clone the repository
git clone https://github.com/pasztor-mark/dotwire.git
cd dotwire

# Create .env from template
cp .env.example .env

# Generate a 32-byte AES-256-GCM symmetric encryption key
echo "Dotwire__Encryption__Keys__k1=$(openssl rand -base64 32)" >> .env

# Generate dev RSA private/public keypair for RS256 token minting
openssl genpkey -algorithm RSA -out dev-jwt.key -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in dev-jwt.key -out dev-jwt.pub

# Set test passwords in .env
echo "POSTGRES_PASSWORD=dotwire_dev_password" >> .env
echo "POSTGRES_APP_PASSWORD=dotwire_app_password" >> .env
echo "Auth__Issuer=dev-host" >> .env
echo "Auth__Audience=dotwire" >> .env
echo "Auth__Keys__dev=\"$(awk '{printf "%s\\n",$0}' dev-jwt.pub)\"" >> .env

3. Launch Stack

docker compose up -d --build

Omit --build to run the published image, ghcr.io/pasztor-mark/dotwire:<version> (linux/amd64 and linux/arm64; set DOTWIRE_VERSION, default 0.4.1).

The compose stacks publish plain HTTP on 127.0.0.1 only. Before exposing dotwire, put TLS in front of it, set Cors:AllowedOrigins and AllowedHosts to your real origins and host names, keep ConnectionStrings:PostgresMigrator on the migrating node only, and for compose.multinode.yaml set NATS_USER, NATS_PASSWORD, POSTGRES_REPLICATION_PASSWORD and HAPROXY_STATS_PASSWORD in .env. Connection strings in compose environment: are visible through docker inspect; in production supply them from your secret store instead. Point the host SDKs at an https baseUrl outside localhost. See ARCHITECTURE.md, "Deployment posture".

4. Verify Health

curl http://localhost:8080/healthz
# Response: 200 OK

5. Seed Test Room & Users

docker compose exec postgres psql -U dotwire -d dotwire -c "
  INSERT INTO user_roles (user_id, role) VALUES ('user-1', 'member'), ('admin-user', 'admin') ON CONFLICT DO NOTHING;
  INSERT INTO room_members (room_id, user_id) VALUES ('00000000-0000-0000-0000-000000000001', 'user-1') ON CONFLICT DO NOTHING;
"

6. Send Your First Message

Follow the @dotwire/host and @dotwire/client quickstarts to mint a token and connect. For this stack, use dev-jwt.key as the private key, with key ID dev, issuer dev-host, and audience dotwire.


Building & Testing Locally

Requires the .NET 10 SDK (global.json pins 10.0.0):

# Build the solution
dotnet build dotwire.slnx

# Run the test suite (Compose integration tests use Postgres and NATS when available)
dotnet test dotwire.slnx

# Publish standalone Native AOT binary
dotnet publish dotwire/dotwire.csproj -c Release

Full documentation: https://dotwire.pasztormark.dev/docs


Official SDKs

Coding agents integrating chat into a host app can start with the SDK guide, which maps each package to its responsibility and shows the participant lookup flow.

Package Environment Purpose Documentation
@dotwire/client Browser / Web / React / Vue / Node.js Real-time chat, scoped rooms, SignalR subscription with gap-fill, typing, presence, history Client README
@dotwire/host Node.js / Next.js / Express Backend RS256 JWT minting, zero-SQL room provisioning, role administration, system messages, webhooks, moderation, audit, retention, DSAR Host README
@dotwire/react React 18+ DotwireProvider, useRoom, useTyping, usePresence, useConnectionState hooks over @dotwire/client React README
Dotwire.Host .NET 8/9/10 C# Backend C# RS256 JWT minting, Presend/PostSend moderation hooks, batched async review, redaction, webhooks, audit, retention, DSAR .NET Host README

Normative Specifications & Documentation

Browse the full docs site at https://dotwire.pasztormark.dev/docs.

The architecture is governed by normative contracts:

  1. PRODUCT.md — Product scope, user personas, and the hard out-of-scope contract.
  2. ARCHITECTURE.md — Write path, read path, NATS backplane, node roles, and fanout disciplines.
  3. AUTH.md — Token specification, claims format, key rotation, and 4-stage authorization pipeline.
  4. COMPLIANCE.md — Compliance controls inventory, encryption, redaction, and audit logging.
  5. AGENTS.md — Hard architectural conventions for AI pair programmers and human contributors.

Upgrading? See UPGRADING.md (0.3 to 0.4 has no breaking changes; 0.2 to 0.3 does).


License

Licensed under the Apache License, Version 2.0.

About

a free, open-source chat layer you embed in your own application. Your app handles its users and signs the JWTs, dotwire handles the rest

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages