colibri/docs/guide/roadmap/channels-plan.md

title
Channels — Implementation Plan

Status: Plan only — no implementation started Last updated: 7.apr.2026 Strategy: see channels-roadmap.md

Current state

v0.9.0 is in development. Telegram is the only channel and is working. Nothing in this plan should be implemented until v0.9.0 is validated in production.

Conclusion

Two channels for v0.9.0: Telegram (done) + Web UI (new). Signal and WhatsApp deferred until real user demand exists. This covers phone dependency, privacy, and global reach without Java or Meta.

---

Exact steps to v0.9.0

Pre-condition: production validate v0.9.0

Before writing a single line of channels code, confirm these work on a real install:

• Telegram bot receives and responds to messages
• npm run backup produces a valid tarball
• npm run doctor reports healthy
• Metrics endpoint responds on port 9100
• Grafana dashboard shows real data from VictoriaMetrics
• ZFS snapshots are being taken by Sanoid
• Management jail starts cleanly on boot

Verify all checks pass before proceeding.

---

v0.9.0 implementation sequence

Step 1 — Onboarding refactor

Make setup channel-agnostic. Currently assumes Telegram unconditionally.

• setup/onboarding.ts — no change needed (doesn't touch Telegram)
• setup/telegram-auth.ts — wrap in a channel selection step so Telegram is one option, not the only option
• src/index.ts — guard TELEGRAM_BOT_TOKEN check behind TELEGRAM_ENABLED=true rather than failing hard if token missing
• .env — add TELEGRAM_ENABLED=true (default true, no breaking change)

Step 2 — Invite code system

New users register by sending a code. Operator generates codes via CLI. Full implementation was prototyped on 16.mar.2026 — see git history or re-derive from channels-plan.md decisions section above.

Files to create:

• src/invite.ts — createInviteCode, tryConsumeInviteCode, jidToFolder
• scripts/invite.ts — npm run invite [--ttl Nd] → prints new code
• scripts/users.ts — npm run users → lists registered users
• scripts/codes.ts — npm run codes → lists all active/used invite codes
• scripts/revoke.ts — npm run revoke <jid> → removes a registered user
• scripts/revoke-code.ts — npm run revoke-code <code> → deletes unused code
• scripts/suspend.ts — npm run suspend <jid> / npm run unsuspend <jid>

Files to modify:

• src/db.ts — invite_codes table (with expires_at, revoked_at), invited_by column on registered_groups, suspended_at on registered_groups
• src/types.ts — invitedBy?: string, suspendedAt?: Date on RegisteredGroup
• src/channels/telegram.ts — onInviteCode? callback in opts, check suspension
• src/index.ts — wire callback, auto-register on valid code, reject suspended JIDs
• package.json — add invite, users, codes, revoke, revoke-code, suspend, unsuspend scripts

Key decisions:

• Single-use codes, optional TTL (default: no expiry)
• Server stores invite_code → JID mapping permanently (enables re-link on browser clear)
• Store invited_by from day one for future delegated invites
• Operator-only invite generation to start (Model A)
• Audit log: logs/invite-audit.log

Step 3 — Web UI channel

Files to create:

• src/channels/web.ts — implements Channel, WebSocket server, JID prefix web:
• Frontend: single HTML/CSS/JS chat page
• setup/web-ui.ts — deploy frontend to CMS jail nginx

Files to modify:

• src/index.ts — start web channel on WEB_UI_PORT if WEB_UI_ENABLED=true
• .env — WEB_UI_ENABLED=false, WEB_UI_PORT=3001
• setup/index.ts — add web-ui step
• setup/pf.ts — allow/restrict WEB_UI_PORT as appropriate

User identity on Web UI: invite code entered on first visit, stored in localStorage. Same invite system as Step 2 — no new concepts for the user.

Step 4 — Version bump and docs

• Bump to v0.9.0
• Update docs/internal/sessions/ with a session log for this work
• Update install docs to mention Web UI and invite codes

---

Part A — Decisions

Decision 1 — End user registration model ✓ DECIDED: Invite code

Operator runs npm run invite → gets a short code (e.g. CLAWDIE-A3X7), shares it out of band. User sends it as their first message. Bot registers them automatically.

---

Decision 2 — Invite code behaviour ✓ DECIDED: Single-use, optional TTL

One code per person, works until used. Store invited_by: jid | 'operator' on every registered user from day one — enables upgrade to delegated invites later without a migration.

Security requirements:

• Optional TTL: npm run invite --ttl 7d (default: no expiry). TTL stored in invite_codes.expires_at (nullable). Expired codes rejected silently.
• Audit log: every code creation and consumption appended to logs/invite-audit.log with timestamp, code, JID (on consume), and source.
• Revoke unused codes: npm run revoke-code <code> hard-deletes an unused code. Used codes cannot be revoked (JID is already registered — use npm run revoke <jid> instead).
• List codes: npm run codes shows all active codes with status:

CODE          CREATED     EXPIRES    STATUS    JID
CLAWDIE-A3X7  2026-03-15  —          used      web:a3x7
CLAWDIE-B9K2  2026-03-17  2026-03-24 active    —

Schema change: add expires_at TIMESTAMP NULL and revoked_at TIMESTAMP NULL to invite_codes table. Rollback migration: DROP COLUMN expires_at; DROP COLUMN revoked_at;

---

Decision 3 — Web UI user identity ✓ DECIDED: Invite code login

User enters their invite code on first Web UI visit. Code becomes their persistent identity — survives browser clears, works on any device. Reuses the same invite system as Decision 1. No OAuth, no Google dependency.

Identity recovery: localStorage is used for convenience (avoids re-entry on repeat visits) but is NOT the authoritative identity store. The server maintains a permanent invite_code → jid mapping in the invite_codes table. If a user clears browser data, entering the same invite code re-links them to their existing JID — no lockout. tryConsumeInviteCode must check for an existing mapping before creating a new JID:

async function tryConsumeInviteCode(code: string): Promise<{ jid: string; isNew: boolean }> {
  const existing = await db.getJidByInviteCode(code);
  if (existing) return { jid: existing, isNew: false };  // re-link, not new
  // ... create new JID, store mapping
}

---

Decision 4 — Signal ✓ DEFERRED

signal-cli requires Java. Java in a jail adds attack surface. No mature non-Java Signal client exists. Revisit only when real users ask for it.

---

Decision 5 — WhatsApp ✓ DEFERRED

Meta-owned, metadata collected, unofficial library only. Revisit only when real users ask for it. If added: use Baileys (pure Node.js, no browser/Puppeteer dependency).

---

Part B — Implementation steps

Step 1 — Onboarding refactor (prerequisite for everything)

What changes:

• setup/onboarding.ts — replace hardcoded Telegram token prompt with channel selection
• setup/telegram.ts — Telegram becomes one option, not the default assumption
• src/db.ts — add invite_codes table, add invited_by field to registered users
• src/index.ts — handle first-message invite code registration logic
• npm run invite — new CLI command to generate invite codes
• npm run users — list registered users with channel and invited_by
• npm run revoke <jid> — remove a registered user

What does not change:

• Channel interface — already correct
• Message pipeline — already channel-agnostic
• JID storage — already channel-prefixed

---

Step 2 — Web UI (Tier 1)

What changes:

• src/channels/web.ts — implements Channel, WebSocket server, JID prefix web:
• src/index.ts — start web channel on WEB_UI_PORT
• Frontend: single HTML/CSS/JS chat page served from CMS jail via nginx
• setup/web-ui.ts — deploy frontend, configure nginx route
• .env — WEB_UI_ENABLED, WEB_UI_PORT
• Invite code entered on first visit → stored in localStorage for convenience
• localStorage is not authoritative — server re-links on re-entry (see Decision 3)

Rate limiting (WebSocket):

• Per-IP: max 10 messages/minute; excess connections dropped with 429
• Per-JID: suspended users rejected at WebSocket handshake (no session created)
• Implementation: in-memory Map<ip, { count, resetAt }> in src/channels/web.ts

Operator user management:

• npm run suspend <jid> — sets suspended_at, blocks all channels for that JID
• npm run unsuspend <jid> — clears suspended_at, restores access
• Suspension does not delete data — full history preserved

Access options:

• Private: Tailscale only (no public exposure)
• Public: chat.yourdomain.com via nginx, invite code is the only gate

---

Step 3 — Signal (deferred)

Add only when real users request it. Java/JRE in a jail is the accepted tradeoff at that point.

---

Step 4 — WhatsApp (deferred)

Add only when real users request it. Tier 2, opt-in, informed-consent warning in setup.

---

Step 5 — WeChat (future / community)

Requires Chinese business registration. Not part of main Clawdie install. JID prefix reserved: wc:

---

Summary

Step	Target version	Priority
1. Onboarding refactor	v0.9.0	Now — blocks everything else
2. Web UI	v0.9.0	Now — solves phone dependency
3. Signal	Future	Only on user demand
4. WhatsApp	Future	Only on user demand
5. WeChat	Community	Not in scope