ChitChat

ChitChat is a small, self-hosted browser chat application. The clean reconstruction reached v2.0.0, the fifth and final planned stable release, adding Web Push notification delivery on top of the stable v1.3.0 baseline. v2.0.1 and v2.0.2 are bug-fix updates on top of it, v2.1.0 through v2.4.0 are maintenance releases with requested additions, v3.0.0 is a larger usability release of maintainer-requested additions, v3.1.0 adds moderating in place and muting, v3.2.0 adds optional guest access, and v3.2.1 tidies up the Operational settings page, described below.

Project status: feature-complete

ChitChat is considered feature-complete. v2.0.0 was the final planned release, and development has officially concluded. This is not an abandonment notice: the project remains supported in the sense that it will only resume work to fix a bug discovered in the shipped surface, or to evaluate a specific, concretely proposed new feature — not to pursue an open-ended roadmap. v2.0.1 and v2.0.2 are exactly that: bug-fix releases with no new feature and no database migration. v2.0.1 fixed findings from an independent post-release security review of the authentication and WebAuthn implementation; v2.0.2 makes the locked dependencies installable on PHP 8.2 and 8.3 and keeps the chat composer in view. v2.1.0 adds two specific, maintainer-requested features under the same policy: unobtrusive registration bot protection with Super-Administrator settings, and a layout that fills the browser with a phone menu. v2.2.0 adds an administrator-editable application name and a small "Powered by ChitChat!" footer, v2.3.0 adds a light theme with a System / Light / Dark setting, and v2.4.0 adds a composer emoji picker and a warmer, more distinctive interface. v3.0.0 is a usability release agreed with the maintainer as one plan: reworked navigation, profile pictures, unread markers, message formatting, slash commands, a typing indicator, ignoring people, Google and Twitch sign-in, two-stage room deletion, and a maintenance lockdown. v3.1.0 lets moderators act where they see a problem, on the message or on the person, and adds muting. v3.2.0 lets a Super-Administrator open chosen rooms to visitors without an account, and adds creating rooms from Administration; v3.2.1 is a cosmetic update on top of it. See the project roadmap for the full status of every feature that was ever considered, the v2.0.0 release notes for what shipped in the final planned release, the v2.0.1 and v2.0.2 release notes for the bug-fix updates, and the v2.1.0, v2.2.0, v2.3.0, and v2.4.0 release notes for the maintenance releases, the v3.0.0 release notes for the usability release, the v3.1.0 release notes for moderating in place, the v3.2.0 release notes for guest access, and the v3.2.1 release notes for the cosmetic update.

Repository status

v3.2.1 is now the supported stable baseline, superseding v3.2.0 and earlier. It adds no migration; upgrading from before v3.2.0 applies the forward-only migration 0039_guest_access.sql (and 0038_user_mutes.sql from before v3.1.0, 0025 to 0037 from before v3.0.0), so operators must back up before upgrading; upgrading from before v2.2.0 also applies 0024_application_name.sql (and 0023_registration_protection.sql from before v2.1.0), so operators upgrading across those releases must back up first. v2.0.0 itself applied the forward-only migration 0022_web_push.sql in place from v1.3.0. Operators deploying either release must back up PostgreSQL and attachment storage together and must not point older source at the migrated database.

The former v0.10.25 source snapshot is incomplete and is not considered runnable or a supported upgrade predecessor. It is preserved on the legacy/v0.10.25 branch for reference.

See CHANGELOG.md, the v3.2.1 stable release notes, the v3.2.0 stable release notes, the v3.1.0 stable release notes, the v3.0.0 stable release notes, the v2.4.0 stable release notes, the v2.3.0 stable release notes, the v2.2.0 stable release notes, the v2.1.0 stable release notes, the v2.0.2 stable release notes, the v2.0.1 stable release notes, the v2.0.0 stable release notes, the v1.3.0 stable release notes, and the project roadmap.

v1 architecture

• PHP 8.2 or newer
• PostgreSQL
• PDO
• Vanilla browser JavaScript
• PHP sessions and CSRF protection
• Server-Sent Events for realtime delivery
• Database-backed expiring presence and SSE-connection leases
• A single application server as the initial deployment target
• Only public/ exposed by the web server
• Opaque attachment storage outside the public web root

The architectural decisions are recorded in docs/architecture/.

Current capabilities

The application currently provides:

• environment-based configuration and forward-only PostgreSQL migrations;
• health and readiness endpoints;
• an Administrator system-status page and an optional bearer-protected Prometheus endpoint;
• user registration and case-insensitive login;
• optional validated birth dates for age-restricted rooms;
• atomic first-user Super-Administrator promotion;
• secure session cookies, CSRF protection, a restrictive CSP, HSTS on secure deployments, and related browser security headers;
• password changes and administrator password resets;
• optional password-first WebAuthn multi-factor authentication with multiple passkeys, one-time recovery codes, exact RP/origin/challenge validation, user verification, and account-facing credential management;
• short-lived, session-version-bound privileged step-up that uses the current password for non-MFA accounts and a passkey or recovery code for MFA accounts;
• optional Super-Administrator enforcement of passkey MFA for all global administrative roles, validated transactionally and backed by a PostgreSQL role-assignment invariant;
• PostgreSQL-backed named rate-limit policies for authentication, MFA, messaging, uploads, invitations, participant search, reports, moderation actions, exports, restoration, and sensitive administrative reads, with bounded environment configuration and aggregate privacy-preserving decision counters;
• kicks, temporary or indefinite bans, and unbans;
• session-version invalidation for active sessions and privileged elevation;
• a user-facing, step-up-protected JSON export of retained account data with explicit privacy boundaries and audited generation;
• step-up-protected account closure with immediate session invalidation, a 14-day cooling-off period, MFA-preserving restoration, maintenance-driven profile tombstoning, and documented username-reuse and retained-shared-data rules;
• durable participant-facing notifications for revision review, moderator room-message deletion, administrator password reset, material installation-policy changes, and mentions, with bounded context, account-scoped read state, and an unread badge;
• optional Web Push delivery of that same notification set to subscribed browsers, with a per-category mute for mentions, per-account quiet hours, per-device subscription management, and delivery through a periodic operator-scheduled sweep rather than a request-time side effect;
• public, unlisted, and invitation-only private rooms;
• optional guest access: a Super-Administrator can let visitors look around as numbered guests, in public rooms that let guests read or also write. Guests can't use direct messages, pings or mentions, are marked everywhere, and global moderators can end a visit or block guests from a connection;
• room owners, moderators, members, minimum-age enforcement, and optional inactivity policies;
• persistent room-message history with pagination;
• authorization-aware PostgreSQL full-text search over current undeleted room and direct-message bodies, with room discoverability, membership, invitation, minimum-age and DM-participant rules enforced inside the query;
• privacy-safe search transport that keeps terms out of URLs, ChitChat audits, rate-limit identifiers and aggregate metric labels, plus exact-message deep links through ordinary history APIs;
• text, /me, and targeted /ping commands;
• database-backed ordered realtime events and SSE cursor reconnection;
• room and global broadcasts;
• forced-disconnect event delivery for account-control actions;
• tab-scoped presence leases with aggregated online-user lists;
• inactivity warnings and active-room expiry without membership removal;
• audited moderator deletion plus author editing and delete-for-everyone controls backed by immutable revision ledgers;
• participant reporting of one specific visible, undeleted room message or incoming direct message through a bounded accessible form;
• an authorization-scoped moderation queue with immutable submitted snapshots, aggregation, assignment, open/in-review/resolved/dismissed states and explicit outcome recording;
• room-owner and room-moderator access limited to their current rooms, while global moderation roles may review DM reports without receiving surrounding conversation history;
• retention-aware moderation evidence that survives canonical message cleanup while active and expires with the exact closure audit under configured audit retention;
• room attachments with MIME and size allowlists, SHA-256 metadata, safe image previews, authorization-aware downloads, editable captions, and retained deletion evidence;
• durable reply references and @username/@room/@here mentions on room and direct messages, resolved and authorized at send time, with composer support (reply banner, quoted preview, @mention autocomplete) and a durable mentioned notification;
• message reactions from a small controlled emoji vocabulary, idempotent add/remove, authorization matching ordinary message-read access, and realtime delivery through the existing event system;
• permanent-by-default two-party direct-message history, unread counts, cursor pagination, targeted realtime events, blocking, editing, delete-for-everyone, and file attachments;
• an unavoidable direct-message privacy notice stating that messages are not end-to-end encrypted and that edits and deletions retain historical bodies until message retention removes them;
• configurable administrative DM inspection, restricted to Super-Administrators by default, protected by recent step-up, and audited on every successful page access;
• separately configurable, disabled-by-default administrative review of exact room or DM revision chains, with recent step-up, a required reason, a successful-access audit that never duplicates historical bodies, and participant-facing disclosure;
• Super-Administrator management of registration, administrative-MFA enforcement, and retention policy, protected by recent step-up for changes;
• dry-run-capable cleanup for retained content, closed moderation evidence, deleted and orphaned room/DM attachments, events, presence, SSE leases, login attempts, throttle rows, and due account closures;
• durable success/failure records for maintenance invocations and ready-to-adapt systemd service/timer units;
• manifest-bound backup, verification, and safe restore commands covering PostgreSQL and attachment storage together, plus ready-to-adapt scheduled-backup units;
• a responsive browser client for registration, password-first MFA login, rooms, history, message search, reporting, live messages, commands, presence, attachments, direct messages, notifications, account security/export/closure/restoration, and logout;
• a permission-aware browser administration and moderation surface for users, roles, bans, room settings, membership, invitations, report cases, audit visibility, eligible DM inspection, exact-ID revision review, operational settings, and system status;
• backup, restore, maintenance, observability, deployment, release, account-lifecycle, passkey/MFA, privacy-notification, search, moderation-reporting, accessibility-review, and browser-testing documentation;
• audit records for sensitive account, authentication, MFA, room, message, attachment, inspection, revision-review, report, moderation-case, settings, export, closure, and maintenance actions;
• PHP lint, PHPStan level 8, JavaScript syntax checks, PostgreSQL-backed integration tests and maintenance validation;
• independent two-session Chromium, Firefox, and WebKit browser journeys, a Chromium virtual-WebAuthn-authenticator journey, and cross-browser structural and keyboard accessibility checks;
• pinned Chromium axe-core WCAG A/AA analysis, document-reflow, forced-colors and reduced-motion checks, plus targeted Linux screenshot regression for stable authentication and account layouts;
• published-release archive installation, first-class backup/restore and forward-upgrade rehearsal;
• real Nginx/PHP-FPM validation of authenticated, unbuffered SSE delivery.

Horizontal scaling and optional external identity (OpenID Connect) integration were considered and intentionally left out of the final release — see the roadmap for why each was deferred rather than pursued. Release-specific manual assistive-technology sign-off remains, as it always has, a per-installation operator responsibility rather than something automated CI can certify once for every deployment.

Installation and operation

See INSTALL.md. API contracts are documented in docs/api/, operating procedures in docs/operations/, and release procedures in docs/releases/.

License

ChitChat is licensed under the BSD 2-Clause License.