Collaboration

Real-time collaboration lets two or more hunters share a Hugin session — same flow capture, shared annotations. One person captures, the other inspects, both see the same events live.

Pro license required for both sides.

🔗Architecture

Hunter A (host)                                     Hunter B (guest)
  Hugin                                               Hugin
    │                                                   │
    │   ─── invite code (out-of-band) ──→               │
    │                                                   │
    │   poll  ┌──────────────────────────┐  poll        │
    └────────►│  Hugin license server    │◄────────────┘
              │  collab relay (HTTPS)    │
              └──────────────────────────┘

Each Hugin instance polls the license server’s collab endpoint over HTTPS. Events are relayed through that server.

Events are end-to-end encrypted with ChaCha20-Poly1305 using a session key derived from the invite code — the relay only sees ciphertext. The license server can’t read your captured flows or annotations.

🔗Hosting a Session

  1. Collaboration view → Share Session (or collab action:"share" via MCP)
  2. Hugin requests a session from the relay; the response includes a session ID, an invite code, and an expiry time
  3. Send the invite code to your guest out-of-band (Signal, Wire, etc.)

A poll loop starts in the background — Hugin checks the relay periodically for new events from connected guests.

🔗Joining a Session

  1. Collaboration view → Join Session (or collab action:"join")
  2. Paste the invite code
  3. Hugin derives the shared session key, joins the session, and starts its own poll loop

The guest sees published events as they arrive. The host’s view of the project is the source of truth — events flow from host actions to guest displays.

🔗What’s Synchronised

The relay carries CollabEvent payloads containing the host’s published annotations. Currently this includes:

  • publish events — explicit annotations sent via collab action:"publish" flow_id:"..." note:"..."

What is not auto-synchronised today:

  • Captured flows (the host’s flow database stays local; guests don’t get a live mirror)
  • Findings creates / updates
  • Scope changes
  • Repeater / Intruder activity

For shared visibility on the deeper data, the host needs to explicitly publish the items they want the guest to see.

🔗Permissions

The collab session is a one-direction broadcast in this implementation: the host publishes, guests receive. There is no role-based permission gating beyond that — both sides need a Pro license, and the invite code controls who can join.

🔗Disconnection

collab action:"leave" cleanly disconnects from the session. The session itself ends when the host leaves; guests are dropped at the next poll.

Sessions also auto-expire at the time returned during creation.

🔗Network

Every collab request goes to the Hugin license server’s collab relay. There is no peer-to-peer transport. If your environment can’t reach the license server, collab won’t work.

The transport is plain HTTPS polling. Encryption of the payload is end-to-end via ChaCha20-Poly1305 — the relay never sees plaintext.

🔗MCP

The collab MCP tool exposes:

  • share — create a session, returns invite code (Pro)
  • join — join via invite code (Pro)
  • status — current session info
  • leave — disconnect
  • publish — send an annotation to the partner (params: flow_id, note)

🔗Roadmap

The current collab is intentionally narrow — encrypted publish/subscribe over a relay. A richer model (auto-mirrored flow streams, role-based write access, find-promote sync) is on the backlog but not yet implemented.