docs/M13-onboarding.md

M13 — Onboarding

Spec version: v1.0 Depends on: M01 (identity), M08 (UI), X04 (config), X02 (events, to emit community.* events), qrcode, Pillow Depended on by: First-run flow in node.py; entry point from M08 settings tab

---

1. Responsibility

The first time a user runs HearthNet, get them from "downloaded a binary" to "joined a community with a working node" in under two minutes. Specifically:

• Generate a device keypair if not present
• Offer two paths: create new community or join existing one
• Create flow: collect community name + policy, sign genesis manifest, display invite QR
• Join flow: scan / paste an invite, redeem it, emit community.member.joined event
• Optional: name the device, choose a profile (defaulted from hardware probe)

Out of scope:

• Federation between communities (Phase 2)
• Multiple-community membership on one device (Phase 2)

---

2. File layout

hearthnet/ui/
└── onboarding.py        # build_onboarding(), redeem_invite(), invite_to_qr()

hearthnet/identity/
└── manifest.py          # build_community_manifest() — reused

A standalone hearthnet init CLI command in M12 shares the same primitives.

---

3. Public API

3.1 onboarding.py

# hearthnet/ui/onboarding.py
from dataclasses import dataclass
import qrcode
from io import BytesIO

@dataclass(frozen=True)
class InviteBlob:
    """The thing that travels between devices to enable joining."""
    schema_version: int          # 1
    community_id:   str          # full
    community_name: str          # display
    inviter_node_id: str         # full
    invitee_node_id: str         # full of the device being invited
    initial_level:   str         # "member" | "trusted"
    bootstrap_endpoints: list[Endpoint]   # how to reach the inviter
    expires_at:     str
    signature:      str          # inviter's signature over canonical-JSON

# --- encoding ---

def encode_invite(blob: InviteBlob) -> str:
    """Compact representation suitable for QR / paste. Format:
    'hearthnet://v1/<base64-url-nopad of canonical-JSON>'.
    Aim: < 500 bytes (fits standard QR at error level M)."""

def decode_invite(text: str) -> InviteBlob:
    """Parse + verify signature. Raises OnboardingError on invalid."""

# --- QR ---

def invite_to_qr_png(blob: InviteBlob, *, box_size: int = 8) -> bytes:
    """Render the invite as a QR PNG. Used by UI for display."""

# --- create flow ---

def create_community(
    name: str,
    policy: CommunityPolicy,
    kp: KeyPair,
    state_dir: Path,
    event_log: EventLog,
) -> CommunityManifest:
    """1. Build genesis community manifest (root = kp).
    2. Persist manifest to <state_dir>/manifest.json.
    3. Append community.created event to event_log.
    4. Append community.member.invited + .joined for root device.
    Returns the manifest."""

# --- join flow ---

def make_invite(
    invitee_node_id_full: str,
    inviter_kp: KeyPair,
    community_manifest: CommunityManifest,
    bootstrap_endpoints: list[Endpoint],
    initial_level: str = "member",
    ttl_seconds: int = 86400,
) -> InviteBlob:
    """Create + sign an invite blob. Also emit a community.member.invited event."""

def redeem_invite(
    blob: InviteBlob,
    our_kp: KeyPair,
    transport_client: HttpClient,
    event_log: EventLog,
) -> CommunityManifest:
    """1. Verify the invite signature, expiry, that invitee_node_id matches us.
    2. Connect to one of bootstrap_endpoints; fetch /community/manifest.
    3. Verify the community manifest's signature chain (root key in invite matches).
    4. Run an initial X02 sync to populate the event log.
    5. Emit a community.member.joined event (our authorship) including our node manifest.
    6. Persist community manifest locally.
    Returns the manifest. Raises OnboardingError on failure."""

# --- UI builders (Gradio components) ---

def build_onboarding(config: Config, kp_provider: Callable[[], KeyPair]) -> 'gr.Blocks':
    """Standalone Blocks UI for the first-run flow. Two-step wizard:
       Step 1: 'Erstmal Schlüssel erzeugen' (auto, with progress)
       Step 2: choice — create or join
         - create: form (name, policy options) → preview manifest → confirm → show QR
         - join:   text area / camera upload for QR → preview invite → confirm → redeem
       Returns the assembled Blocks. node.py mounts this BEFORE the main UI when
       config.community.community_id is None."""

class OnboardingError(Exception):
    """code in {'invite_invalid','invite_expired','invitee_mismatch','bootstrap_unreachable',
              'community_manifest_invalid','sync_failed','already_member'}"""
    code: str

---

4. Flows in detail

4.1 Create-community flow

User clicks "Neue Community gründen"
  ↓
Form:
  • Community name (free text, 1..64 chars)
  • Allow new members to invite? (default true)
  • Minimum signatures to revoke a member: 3 (advanced)
  ↓
On submit:
  policy = CommunityPolicy(
      min_signatures_to_invite = 1,
      min_signatures_to_demote = 3,
      min_signatures_to_revoke = 3,
      capability_token_ttl_seconds = 86400,
      federation_enabled = True,
      default_member_can_invite = checkbox_value,
  )
  manifest = create_community(name, policy, our_kp, state_dir, event_log)
  config.community.community_id = manifest.community_id
  X04.save(config)
  ↓
"Du bist Gründer!" panel
  • Show community short id
  • Show your role: anchor
  • Show QR code for inviting first member (preconfigured invite to ANY device)
    → actually: show a "create invite" button that asks for the invitee's NodeID
  ↓
Continue → main UI

4.2 Join-community flow

User clicks "Einer Community beitreten"
  ↓
"Wie hast du die Einladung erhalten?"
  • Paste link / text
  • Upload QR image
  • Use camera (mobile only)
  ↓
decode_invite(text or scan) → InviteBlob
  • verify signature
  • check expiry
  • check invitee_node_id == our_node_id_full
  ↓
Preview:
  • Community name
  • Inviter display name (lookup via bootstrap_endpoints[0]/manifest)
  • Initial level: member
  • "Beitreten" button
  ↓
On confirm:
  redeem_invite(blob, our_kp, transport_client, event_log)
    → fetch community manifest from bootstrap
    → run X02 sync to fetch all history
    → emit community.member.joined event
    → persist community manifest
  config.community.community_id = blob.community_id
  X04.save(config)
  ↓
"Willkommen!" → main UI

4.3 Inviting someone (post-onboarding, from settings tab)

Settings → "Mitglied einladen"
  ↓
Two options:
  (a) Generate invite for a specific NodeID
       - user pastes invitee NodeID full form (they got it from their device)
       - or scans a "I'm a fresh device" QR shown on their screen
  (b) Use the in-person setup wizard (Phase 2: BLE pairing)
  ↓
make_invite(...) → InviteBlob
  • Emit community.member.invited event (so the rest of the community knows)
  • Display QR for the invitee to scan
  • Expires in 24h

4.4 "I'm a fresh device" QR

Before joining, a freshly-installed device displays a QR encoding only its node_id_full (no signature; this is a public key). The inviter scans this QR with their existing device to build an invite. Format:

hearthnet-id://v1/<base64-url-nopad of {"node_id_full": "...", "display_name": "Hannes' Tablet"}>

This is unsigned because nothing private is in it. The inviter is the source of trust.

---

5. Behaviour

5.1 First-run detection

node.py checks at startup:

if config.community.community_id is None:
    # mount onboarding UI; don't start most services yet
    ...
else:
    # normal startup

After the user completes onboarding, node.py continues with the full startup sequence (now with a valid community).

5.2 Re-onboarding (changing community)

The settings tab has a "Leave community" action. After confirm, the local data for that community is moved to <DATA>/communities/<id>.archived/ and the user is sent back to onboarding. The user keeps the same keypair unless they explicitly choose to regenerate it (which then makes a new identity).

5.3 What we sign and what we don't

Artifact	Signed by	Why
Invite blob	Inviter	So invitee can prove this came from a member
Genesis community manifest	Founder (root)	Establishes the root of trust
community.member.joined event	The joining device	Asserts "I am here, with this manifest"
Fresh-device ID QR	Nobody	It's just a public key; sees + uses

5.4 Failure modes during join

• Bootstrap endpoints unreachable → bootstrap_unreachable with retry option
• Invite expired → invite_expired, must request a new one
• Invitee mismatch → invitee_mismatch (someone tried to redeem someone else's invite)
• Already a member → already_member, no-op with a message

5.5 Privacy of invites

An invite contains:

• Community ID, name
• Inviter NodeID
• Invitee NodeID
• Bootstrap endpoints

It does not contain the event log. Anyone seeing an invite knows the community exists and who is who, but not what was said in it.

---

6. Errors

OnboardingError codes:

• invite_invalid — malformed or bad signature
• invite_expired — past TTL
• invitee_mismatch — invite addressed to a different NodeID
• bootstrap_unreachable — can't reach inviter for manifest fetch
• community_manifest_invalid — fetched manifest fails verification
• sync_failed — initial event-log sync failed
• already_member — we're already in this community

---

7. Configuration

No new config keys. Uses config.identity.* and config.community.* from X04.

---

8. Tests

Unit

• test_invite_encode_decode_roundtrip
• test_invite_qr_under_500_bytes
• test_invite_expired_rejected
• test_invite_addressed_to_someone_else_rejected
• test_create_community_emits_three_events (created + invited self + joined self)
• test_redeem_invite_results_in_joined_event

Integration

• test_two_node_join_flow_end_to_end — node A creates community, generates invite, node B redeems, both see each other as members
• test_join_during_partial_partition — bootstrap unreachable, retry succeeds
• test_redeem_then_immediately_sync_marketplace — historical posts visible after sync

---

9. Cross-references

What	Where
Community manifest schema	CONTRACT §6.2
community.* events	CONTRACT §7.2
Identity primitives	M01
UI integration	M08 §8.5
CLI hearthnet init	M12 §3
Event log + sync	X02

---

10. Open questions

1. Multi-community membership — out of scope MVP. Phase 2: same keypair, multiple <DATA>/communities/<id>/ dirs.
2. Recovery if device key lost — currently impossible (key = identity). Phase 2: "social recovery" via 2-of-3 trusted members re-issuing a re-joined identity.
3. BLE pairing — Phase 2; faster than QR for adjacent devices.
4. Camera capture on mobile web — getUserMedia is available; needs HTTPS. Self-signed cert may trip browsers; document workaround.