Topolo Chat

Public overview of the collaboration surface for channels, direct messages, meetings, guests, and remote-assist workflows.

publicverified 2026-08-10chatmeetingscollaboration

What It Is

Topolo Chat is the collaboration application for channels, direct messages, meetings, guest access, transcripts, future remote-assist workflows, and the shared cross-app Chat widget used by eligible Topolo apps.

Architecture

Chat combines a Cloudflare-native backend, a web client, realtime and meeting bindings, and optional desktop and mobile shells. Cross-app HTTP policy is owned by the shared Worker runtime: Chat no longer adds permissive wildcard CORS headers itself.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

The primary public surface is https://chat.topolo.app; staging mirrors it at https://chat.stg.topolo.us with a staging-specific browser build so Auth and app-origin calls stay inside the staging installation. Assigned users can also access Chat through the shared @topolo-io/app-shell bottom-right widget, which mounts only after Auth confirms the topolo-chat service is assigned. The widget preserves lightweight UI continuity across first-party app switches while message data remains owned by Chat.

API Reference

The current contract is curated in the docs platform and centers on channels, DMs, uploads, meetings, guests, notifications, notes, audit events, remote-assist transport, and compact widget endpoints under /api/widget/chat. Shared CORS handling reflects an allowed first-party origin and the requested canonical resource headers, including X-Topolo-Resource-ID and X-Topolo-Resource-Type, for widget preflight and authenticated responses.

Auth and Permissions

Topolo Chat uses Topolo Auth for organization-scoped workspace access. Protected workspace bearer-token requests validate through Auth and do not accept locally decoded JWT claims from a Worker secret. Browser login handoff, SSO callback-code redemption, and returning-user cookie hydration delegate to the shared Topolo Auth client after Chat resolves the Auth-owned topolo-chat service slug at runtime, while guest meeting entry remains intentionally separate from normal workspace membership. Workspace-admin paths such as API key management now require explicit Chat service permissions instead of relying on local role-name heuristics. For first-party Topolo users, /login renders Chat's branded shared LoginPage directly in the Chat shell. Hosted Auth login pages are reserved for third-party/provider handoff, not the default credential form.

Data Ownership

Chat owns organization-scoped workspace, membership, channel, DM, message, upload, meeting, guest, transcript, audit, remote-assist session state, and the runtime projection of Agent personas used by the cross-app widget. Its bootstrap API returns organization, organizationPolicies, and organizationMembers as the canonical tenant payload keys.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /threads, its offline policy is read_through_cache, and it requires organization context.

Published permissions: chat.threads.read, chat.messages.write.

  • /threads uses /api/channels with the chat.threadList template and chat.threads.list data source.
  • /threads/:id uses /api/channels/:id/messages with the chat.thread template and chat.threads.detail data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Chat deploys as a Cloudflare-backed collaboration app with optional desktop and mobile client shells.

Failure Modes

  • meeting join token flow drifts from guest or mobile launch flows
  • realtime or Durable Object bindings are unavailable
  • guest entry is mistakenly treated as normal workspace auth
  • a first-party widget origin or canonical resource header is absent from the shared Worker CORS policy, causing preflight to fail before Chat authorization runs

Debugging

Start with /systems/topolo-chat, then separate workspace-auth issues from guest and meeting-launch issues before debugging deeper. For a cross-app widget failure, inspect the OPTIONS response first: it should return 204, reflect the allowed caller origin, and echo the requested authorization and canonical resource headers through the shared Worker runtime.

Use It

Open Chat for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-chat --json
topolo actions --service topolo-chat --json
topolo actions capabilities --service topolo-chat --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Chat and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Released exact source bdd5b110982ff4e77e0416c72bd300d241f74af6 to staging and production on 2026-08-10 with one D1-held tprk1 application root under the Store-only environment master. Protected fields use tp2, scoped blind indexes derive from tpk1 data keys, and the administrative surface contains root diagnostics, root provision/rewrap, data-key rotation, and a read-only canary. Production reports zero unprotected fields or objects.

  • Verified staging source c3c4e9c772516a2ccad3e4f84c3b330ad81b1af2 on 2026-08-01: the final wildcard override is removed, live preflight denied an untrusted origin without credential headers, and both tested first-party origins were reflected by the shared allowlist.

  • Reconciled Chat staging 9f2f0649e187 on 2026-07-31. Chat removed its app-local wildcard CORS implementation and now delegates preflight and response headers to the shared Worker runtime, which reflects allowed Topolo origins and canonical resource headers for the cross-app widget.

  • Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found.

  • Verified the native_capability mobile experience contract and its 2 published route(s) against apps/TopoloChat origin/staging 0270c5f5661e on 2026-07-27.

  • Reconciled this page against apps/TopoloChat origin/staging d8e25b13511d on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloChat commits through d487fd0; reviewed 58 commits since 2026-06-25, including d487fd0 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 910917a chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); b577a36 Stop blocking startup on i18n readiness; 8ddd18d Remove meeting join scaffold overlay.

  • Persisted lightweight cross-app Chat widget UI state through Auth preferences on 2026-07-02 while keeping message content in Chat.

  • Added cross-app Chat widget ownership and widget API coverage on 2026-06-18.

  • Renamed Chat's local tenant-scoping API and D1 columns from workspace to organization on 2026-05-10.

  • Removed hard-coded Chat Auth app IDs on 2026-05-13 so login, callback preboot, worker auth validation, notification events, widget output, API-key management, and seed intake use slug-resolved app identity.

  • Verified Chat staging origin isolation on 2026-04-30.

  • Removed Chat's hosted Auth redirect from /login on 2026-04-20 so first-party users sign in through the branded embedded shared LoginPage.

  • Removed the Chat worker's residual local TOPOLO_JWT_SECRET handoff on 2026-04-18 so protected workspace bearer-token requests validate through Auth.

  • Delegated Chat web login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18.

  • Added service-scoped Auth cookie hydration to Chat startup on 2026-04-18 so returning users can enter without a full hosted login redirect.

  • Standardized Chat admin permission checks on 2026-04-10 so API key management now follows the shared Auth permission model instead of local role checks

  • Standardized the public product label to Chat across the web shell, workspace bootstrap text, and meeting handoff flows on 2026-04-04

  • Added canonical Topolo Chat coverage and retired repo-local collaboration docs on 2026-03-30