social.io is a self-hosted communication application that brings mail, chat, calls, letters, calendar, meetings, shared inboxes, and an embeddable support widget into one Deno service and Lit web application. It exposes a typed RPC API for the first-party client, a REST integration API, WebSocket push, and a JMAP mail server over HTTP.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Current implementation status

The v7 application is feature-complete for its shipped provider contracts. A release or published image is still distinct from a production deployment; real infrastructure, DNS/TLS, backups, monitoring, and rollback qualification remain deployment-owner gates.

Surface	Current state
Unified inbox	Cross-channel projection, triage, person timelines, deterministic AI fallback
Mail	IMAP/JMAP provider import, SMTP send, account provisioning, drafts, attachments, screener, JMAP, and a first-party IMAP server
Chats	DMs, groups, channels, membership administration, attachments, replies, edits, deletion, reactions, typing, presence, and read state
Organizations	Organizations, roles, workspaces, teams, invitations, storage quotas, and administration UI
Spaces	Shared-inbox queues, assignment, internal notes, and audit events
Widget	Site configuration, embeddable loader, visitor sessions, chat, and email continuation
Calendar and meetings	Scheduling, free/busy, invitations, recaps, and routed actions; live media/transcription providers are not connected
Calls	Logs, voicemail, transcripts, and provider contracts; telephony and STT providers are not connected
Letters	Compose, tracking, scan/PDF storage, and provider contracts; postal and scan-hub providers are not connected
Authentication	Password sessions, email verification/reset, refresh/revocation, role guards, TOTP MFA, and encrypted TOTP state

The client-facing IMAP backend, UID migration, OAuth authentication, TLS runtime configuration, readiness, drain, and JMAP/IMAP change fan-out use published SmartIMAP 2.1. Provider accounts support IMAP implicit TLS/mandatory STARTTLS, JMAP, SMTP implicit TLS/mandatory STARTTLS, password or OAuth authentication, encrypted persistence, token refresh, and test-before-save management in the settings UI.

Mail deletion is shared across REST, JMAP, IMAP EXPUNGE/mailbox removal, and account disconnect. Migration mail:10 adds protocol-hidden Email tombstones, parent-scoped attachment cleanup outboxes, and indexed recovery for deferred S3 cleanup and crash-interrupted IMAP APPEND/COPY blob links. A committed protocol deletion no longer depends on object storage being immediately available, and stale writers cannot resurrect a tombstoned Email.

Published SmartJMAP 2.1 and SmartSMTP 4.2 are checked by semantic capability markers; mail:9 migrates and encrypts the canonical SMTP credential shape. Interfaces 3.0 is fully adopted, including account recovery, optimistic draft revisions, chat profile snapshots, provider-account contracts, and dedicated letter PDF references. Migration chat:1 backfills snapshots and letter:1 separates legacy PDFs from ordered page images.

Architecture

Deno 2 backend using Deno.serve
Lit frontend bundled into TypeScript modules and embedded in the runtime
MongoDB persistence through @push.rocks/smartdata
S3-compatible attachment storage through @push.rocks/smartbucket
@api.global/typedrequest contracts at POST /typedrequest
authenticated WebSocket push at /ws
public REST integration surface under /api/v1
JMAP discovery/API/upload/download/EventSource endpoints on the HTTP origin
first-party implicit-TLS IMAP server integration on a separate TCP listener
upstream IMAP/SMTP clients for provider mail
clamd malware scanning with fail-closed production configuration

MongoDB, object storage, clamd, and transactional SMTP are external services. The supported initial production topology uses one application replica because JMAP change state, IMAP IDLE fan-out, and realtime fan-out are process-local.

Local development

Prerequisites:

Deno 2
pnpm 11
MongoDB
S3-compatible object storage such as MinIO

Install with the frozen lockfile and build all three embedded browser bundles:

pnpm install --frozen-lockfile
pnpm run build

Create .nogit/env.json for local development:

{
  "SOCIALIO_RUNTIME_MODE": "development",
  "MONGODB_URL": "mongodb://localhost:27017/socialio",
  "MONGODB_DB": "socialio",
  "S3_ENDPOINT": "http://localhost:9000",
  "S3_ACCESS_KEY": "minioadmin",
  "S3_SECRET_KEY": "minioadmin",
  "S3_BUCKET": "socialio",
  "JWT_SECRET": "local-development-secret-at-least-16-bytes",
  "EMAIL_CREDENTIALS_KEY": "local-mail-key-at-least-32-bytes-long",
  "MFA_TOTP_ENCRYPTION_KEY": "local-totp-key-at-least-32-bytes-long",
  "PORT": 3000
}

Run the complete frontend/backend watcher:

pnpm run watch

deno task dev watches the backend while serving the last generated bundles. Open http://localhost:3000 after startup.

Production

The production container builds browser assets from the frozen pnpm lockfile, caches the Deno dependency graph, runs as an unprivileged user, handles signals through tini, and uses /readyz for its health check:

docker build --pull --tag socialio:<revision> .

Use .env.example as the environment contract and inject real values from the deployment platform's secret store. Production validation requires authenticated TLS MongoDB, HTTPS object storage, private clamd, independent encryption/signing keys, HTTPS PUBLIC_APP_URL, and transactional SMTP over implicit TLS on port 465. When email is enabled, it also requires a first-party IMAP hostname and read-only TLS certificate/private-key paths.

Deployment topology, probe semantics, graceful drain, backup, restore, rollback, and incident procedures are documented in docs/operations.md.

Standalone binaries remain available:

deno task release
deno task compile:linux-x64
deno task compile:linux-arm64
deno task compile:macos-x64
deno task compile:macos-arm64

Runtime endpoints

Endpoint	Purpose
`GET /livez`	Process liveness without dependency I/O
`GET /readyz`	MongoDB, storage, scanner, realtime, JMAP, IMAP, mail scheduler, and transactional-email readiness
`POST /typedrequest`	First-party typed request/response API
`GET /ws`	Authenticated realtime and widget WebSocket transport
`/api/v1/*`	Bearer-authenticated REST integration API
`GET /.well-known/jmap`	JMAP session discovery
`POST /jmap/api`	JMAP method calls
`/jmap/upload/*`	JMAP blob upload
`/jmap/download/*`	JMAP blob download
`GET /jmap/eventsource`	JMAP StateChange EventSource push
TCP `993`	First-party IMAP over implicit TLS; XOAUTH2/OAUTHBEARER only
`GET /widget.js`	Cross-origin embeddable widget loader

REST and WebSocket identities are derived from verified access tokens. A user socket authenticates once with this envelope before subscribing:

{
  "type": "authenticate",
  "token": "<access-token>"
}

Channel and conversation subscriptions are membership-checked by the server. Widget visitors use the separate site/session authentication flow.

Programmatic usage

The package entrypoint is import-safe and exports the application API:

import { SocialIO } from './mod.ts';

const app = new SocialIO({
  runtimeMode: 'development',
  mongoUrl: 'mongodb://localhost:27017/socialio',
  mongoDb: 'socialio',
  s3Endpoint: 'http://localhost:9000',
  s3AccessKey: 'minioadmin',
  s3SecretKey: 'minioadmin',
  s3Bucket: 'socialio',
  jwtSecret: 'local-development-secret-at-least-16-bytes',
  emailCredentialsKey: 'local-mail-key-at-least-32-bytes-long',
  mfaTotpEncryptionKey: 'local-totp-key-at-least-32-bytes-long',
  port: 3000,
});

await app.start();

// On application shutdown:
await app.stop();

createSocialIOFromEnv() reads process environment variables. createSocialIOFromEnvFile() overlays .nogit/env.json for local development.

Project layout

mod.ts                 CLI and import-safe package entrypoint
ts/                    backend, domain managers, models, services, transports
ts_migration/          lease-protected startup data migrations
ts_web/                Lit application
ts_web_widget/         embeddable widget frame and loader
ts_bundled/            generated embedded browser bundles
html/                  application and widget HTML shells
test/                  Deno unit, integration, authorization, and lifecycle tests
docs/operations.md     production operations and recovery runbook

Commands

pnpm run build         # build app, widget frame, and widget loader bundles
pnpm run watch         # rebuild bundles and restart the backend on changes
deno task start        # start from process environment
deno task dev          # backend watch using .nogit/env.json
deno task test         # run the Deno test suite
deno check mod.ts      # type-check the application dependency graph
deno fmt --check       # verify Deno formatting
deno lint              # run Deno lint

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@social.io/social.io