Design Document

This is the canonical technical reference for ItsGoin. It describes the vision, the architecture, and the current state of every subsystem — with full implementation detail. This document is versioned; each update records what changed.

1. The Vision

The honest promise: The CDN is an attention-driven delivery amplifier, not a storage guarantee. Hot content spreads naturally through demand; cold content decays unless intentionally hosted. Authors are responsible for their own content durability — a post backup/export tool is the author's safety net, not the network's job. The system is a loss-risk network — best-effort availability, not durability guarantees.

Guiding principles

• Our distributed network first, direct connections always preferred
• Social graph and friendly UX in front, infrastructure truth in back
• Privacy by design: public profile is minimal, private profiles are per-circle, social graph visibility is controlled
• Don't break content addressing (PostId = BLAKE3(post), visibility is separate metadata)
• Your feed is yours: reverse-chronological by default, no algorithmic ranking, user-controlled discovery
• Three separate layers — Mesh (structural backbone), Social (follows/audience/DMs), File (content storage/distribution) — each with its own connections and routing

2. Identity & Bootstrap

First startup

1. Identity: Load or generate ed25519 keypair from {data_dir}/identity.key. NodeId = 32-byte public key. A unique device identity is also generated for multi-device coordination (see Section 23).
2. Storage: Open SQLite database (distsoc.db), auto-migrate schema.
3. Blob store: Create {data_dir}/blobs/ with 256 hex-prefix shards (00/ through ff/).
4. UPnP mapping: Attempt UPnP/NAT-PMP port mapping (2s timeout). If successful, store external address for advertisements. Do not block startup if unavailable. See Section 11.
5. NAT type detection: STUN probes to two public servers (3s timeout each). Classifies as Public/Easy/Hard/Unknown. UPnP success overrides to Public. Anchors skip probing. Result stored on ConnectionManager, shared in InitialExchangePayload, stored per-peer. See Section 10.
6. Stale N2/N3 sweep: Remove all N2/N3 entries tagged to peers not in the current mesh. Clears stale reach data from previous sessions (e.g., unclean shutdown).
7. Bootstrap anchors: Load from {data_dir}/anchors.json. If missing, use hardcoded default anchor.
8. Bootstrap: If peers table is empty, connect to a bootstrap anchor. Request referrals and matchmaking (unless self or the other node is an anchor). Persist on that anchor's referral list until released (at referral count limit) while beginning the growth loop immediately.

Startup cycles

Spawned after bootstrap completes:

3. N+10 Identification

Concept

Every node is identified not just by its NodeId but by its N+10: the node's own NodeId plus the NodeIds of its 10 preferred peers. This accelerates the capacity to find any node — if you can reach any of the 11 nodes in someone's N+10, you can find them.

Where N+10 appears

Why this works

Preferred peers are bilateral agreements — stable, long-lived connections. By including them in identification, any node that can find any of your 10 preferred peers can transitively find you within one hop. This eliminates most discovery cascades for socially-connected nodes.

Status: Partial

N+10 is partially implemented — preferred peers exist and are tracked, but N+10 is not yet included in all identification contexts (post headers, blob headers, self-identification messages). Currently preferred_tree in social routes provides similar functionality for relay selection.

4. Connections & Growth

Connection types

• Mesh connection — long-lived routing slot. Structural backbone for discovery and propagation. DB table: mesh_peers.
• Keep-alive session — long-lived connection for social or file layer peers that aren't in the mesh 101. Participates in N2/N3 routing. See Section 16.
• Session connection — short-lived, held open for active interaction (DM conversations, group activity, anchor matchmaking). Tracks remote_addr so the relay can inject observed addresses for session peers during introductions.
• Ephemeral connection — single request/response, no slot allocation.

Slot architecture

MeshConnection struct

Each mesh connection tracks: node_id, connection (QUIC), slot_kind (Preferred or NonPreferred), remote_addr (captured from Incoming before accept), last_activity (AtomicU64), created_at.

Mutual mesh blacklist Planned

Targeted two-node stranger relationship. Both nodes opt in, maintaining genuine N2 stranger status indefinitely regardless of growth loop behavior. Stored in a local mesh_blacklist { node_id } table.

• Growth loop skips blacklisted nodes during candidate selection
• Incoming mesh upgrade from blacklisted node → respond with RefuseRedirect (0x05)
• Both nodes must add each other — asymmetric blacklist is valid but only prevents the blacklisting side from upgrading
• Blacklisted nodes remain visible in N2 via shared N1 peers
• Full session/ephemeral interaction still works — messages, probes, routing participation
• Never consume each other's mesh slots

Production utility: Operators maintaining intentional stranger relationships for network diversity, preventing specific nodes from becoming preferred peers, or any scenario where two nodes want to cooperate at session level without mesh entanglement.

--max-mesh <n> CLI flag Planned

Topology control at network scale. Forces a node to cap its mesh connections, keeping it permanently in N2 of other nodes. Testing affordance only — not for production use.

• --max-mesh 0: Pure N2 participant, never takes mesh slots. Warning: free rider — consumes routing knowledge without carrying mesh load.
• --max-mesh 3: Partial mesh, useful for testing sparse topologies
• --max-mesh 101: Default, full normal behavior
• Node responds to all protocol messages normally, never initiates or accepts mesh upgrades beyond the cap
• Reuses existing RefuseRedirect (0x05) — no new protocol machinery

Keepalive

• Interval: 30 seconds (MeshKeepalive message, 0xE0)
• Zombie detection: No stream activity for 600s (10 min) = zombie, removed in rebalance
• last_activity updated on every stream accept

5. Connection Lifecycle

5.1 Growth Loop (60s timer + reactive on N2/N3 receipt)

Timer: Fires every 60 seconds. Checks current mesh count. If < 101, runs a growth cycle.

Reactive trigger: Fires immediately after receiving a peer's N2/N3 list (from initial exchange or routing diff). Continues firing on each new N2/N3 receipt until mesh is 90% full (~91 connections). After 90%, switches to timer-only mode.

Candidate selection (N2 diversity scoring):

score = 1.0 / reporter_count + (0.3 if not_in_N3)

• Fewer reporters = higher diversity = better candidate
• Bonus for locally-discovered peers (not transitive)
• Sorted descending, best candidate tried first
• Growth loop goes wide by default — no local/wide distinction
• Blacklist filter: Skip nodes in mesh_blacklist table (see Section 4)

Connection attempt cascade:

1. Direct connect (15s timeout) — use stored/resolved address
2. Introduction fallback — find N2 reporters who know this peer, ask each to relay-introduce us

Failure handling: Track consecutive failures. After 3 consecutive failures, back off (break loop, wait for next signal). Mark unreachable peers for future skipping.

5.2 Rebalance Cycle (every 600s)

Executed in priority order:

1. Dead connection removal: Remove connections with close_reason() set, or idle > 600s (zombie)
2. Stale entry pruning: N2/N3 entries tagged to a peer that is no longer connected are pruned immediately (on disconnect and on startup sweep). Age-based fallback: entries older than 7 days. Social route watchers older than 30 days.
3. Priority 0 — Preferred peer reconnection: Iterate preferred_peers table, reconnect any that are disconnected. If at capacity, evict the lowest-diversity non-preferred peer to make room. Prune preferred peers unreachable for 7+ days (slot released, does NOT auto-return on reconnect — must re-negotiate via MeshPrefer). After 7 days, social checkin frequency drops from 1–3 hours to daily until the 30-day reconnect watcher expires.
4. Priority 1 — Reconnect recently dead: Re-establish dropped non-preferred connections. Skip blacklisted nodes — do not attempt reconnection to peers in mesh_blacklist.
5. Priority 2 — Signal growth loop: Fill remaining empty slots via growth loop
6. Idle session cleanup: Reap interactive sessions idle > 300s (5 min). Keep-alive sessions are NOT reaped by idle timeout.
7. Relay intro dedup pruning: Clear seen_intros entries older than 30s, cap at 500

5.3 Recovery Loop (reactive, mesh empty)

Trigger: disconnect_peer() fires when last mesh connection drops.

1. Debounce 2 seconds (wait for cascading disconnects to settle)
2. Gather anchors: known_anchors table ordered by last_seen DESC (LIFO — most recently seen is most likely still reachable) → fallback to hardcoded default anchor(s) only if known_anchors empty or exhausted
3. For each anchor: connect, request referrals and matchmaking, try direct connect to each referral, fallback to hole punch via anchor for unreachable referrals
4. Persist on anchor's referral list until released, begin growth loop immediately
5. Post-bootstrap stale anchor cleanup: After successful bootstrap/recovery, probe known_anchors entries where last_seen > 7 days. Success: update last_seen. Failure: DELETE from known_anchors. Reuses existing anchor probe machinery (0xC3/0xC4). No new cycle or timer — runs as final step of bootstrap/recovery.

5.4 Initial Exchange (on every new connection)

When two nodes connect, they exchange:

• N+10: Our NodeId + 10 preferred peers' NodeIds
• N1 share: mesh peers + social contacts NodeIds (merged, no addresses)
• N2 share: deduplicated N2 NodeIds (no addresses)
• Profile: PublicProfile (display name, bio, avatar CID, public_visible flag)
• Delete records: Signed post deletions
• Post IDs: All local post IDs (for replica tracking)
• Peer addresses: N+10 address list for connected peers

Processing: Their N1 → our N2 table (tagged to reporter). Their N2 → our N3 table (tagged to reporter). Store profile, apply deletes, record replica overlaps. Trigger growth loop immediately with new N2/N3 candidates if mesh < 90% full.

5.5 Incremental Routing Diffs (every 120s + on change)

NodeListUpdate (0x01) contains N1 added/removed, N2 added/removed. Sent via uni-stream to all mesh peers and keep-alive sessions. Receiver processes: their N1 adds → our N2 adds, their N2 adds → our N3 adds, etc.

6. Network Knowledge Layers (N1/N2/N3)

<N4 access

A node has <N4 access to a target if the target appears in its N1, N2, or N3 tables. This means the target is reachable within 3 hops without needing worm search or relay introduction. The social/file connectivity check (see Section 16) uses <N4 access to determine whether keep-alive sessions are needed.

What is NEVER shared

• Addresses (resolved on-demand via chain queries)
• N3 entries (search-only, never forwarded)
• Duplication counts (topology leak)
• Which NodeIds are social contacts vs mesh peers (merged in N1 share)

Address resolution cascade (connect_by_node_id)

7. Three-Layer Architecture (Mesh / Social / File)

The network operates across three distinct layers, each with its own connections, routing, and purpose. The separation enables specialized behavior without the layers interfering with each other.

Key principle: mesh is not for content

Pull sync does not pull posts from mesh peers. Mesh connections exist for routing diversity and discovery. Content flows through the social layer (posts from people you follow) and the file layer (blobs from upstream/downstream hosts). This separation means mesh connections can be optimized purely for network topology without social bias.

Cross-layer benefits

Each layer's connections contribute to finding nodes and referrals for the other layers. Keep-alive sessions from the social and file layers participate in N2/N3 routing, which improves <N4 access for all three layers. A social keep-alive session might provide the N2 entry that helps the mesh growth loop find a diverse new peer, and vice versa.

8. Anchors

Intent

Anchors are "just peers that are directly reachable" — standard ItsGoin nodes with a routable address. They run the same code with no special protocol. Their value comes from being directly connectable for bootstrapping new nodes into the network and matchmaking (introducing peers to each other). Anchors include VPS-deployed nodes (always-on) and desktop nodes with UPnP port mappings (see Section 11).

Each profile can carry a preferred anchor list — infrastructure addresses, not social signals.

Status: Complete (with gaps)

When anchors are used

• Bootstrap: First startup with empty peers table. Connect to anchor, request referrals and matchmaking, persist on referral list while growing mesh.
• Recovery: When mesh drops to 0 connections. Same flow as bootstrap.
• Not ongoing: Nodes do NOT register with anchors on a loop. Anchors are for forming initial connections, not for ongoing presence.
• itsgoin.net node: A permanent, well-connected ItsGoin node runs on itsgoin.net as part of the share link redirect infrastructure (see Section 26). This node participates in the network as a standard anchor — it bootstraps new nodes, accepts referral requests, and is included in known_anchors by peers that connect through it. It is not special-cased in the protocol. Its value as an anchor comes from permanent uptime and high mesh connectivity, not from any privileged role.

Anchor referral mechanics

When a bootstrapping node connects, the anchor provides referrals from its mesh and referral list. The node persists on the anchor's referral list until released at the referral count limit. During this time, the anchor can matchmake — introducing the new node to other peers requesting referrals.

Anchor selection order

1. known_anchors table — ORDER BY last_seen DESC (LIFO). The most recently seen anchor is most likely still reachable, particularly given short-lived home desktop anchors.
2. Hardcoded default anchor(s) — only if known_anchors is empty or exhausted. A brand-new node hits hardcoded anchors once on first bootstrap, populates known_anchors from that session, and the hardcoded list recedes to pure fallback.

No scoring, no success counting, no prediction. Attempt, move to next on failure. The known_anchors table stores only: node_id, addresses, last_seen.

Anchor self-verification Complete

Nodes with UPnP-mapped IPv4 or IPv6 public addresses cannot self-certify as anchors — they need external verification that they are genuinely reachable by cold direct connect. A node is a viable anchor only if a complete stranger can connect to it directly with no introduction, no hole punch, and no relay.

Witness selection

Node A (candidate anchor) selects a witness from its own N2 table entries NOT present in its N1. These are genuine strangers — no prior connection, no cached address, no warm path. A selects one (call it C) and knows C's address via the N1 reporter (call it B) who reported C in their N1 share.

Probe message flow

A → B (N1 reporter of C): AnchorProbeRequest {
    target_addr,     // A's external address to test
    witness,         // C's NodeId
    return_via,      // B's NodeId (for failure reporting)
}

B → C: forward AnchorProbeRequest

C: cold direct QUIC connect to target_addr
   — MUST use only raw QUIC connect (step 1 of connect_by_node_id)
   — MUST skip entire resolution cascade, hole punch, introduction, relay
   — 15s timeout

SUCCESS: C → A directly (on new connection): AnchorProbeResult { reachable: true }
FAILURE: C → B → A: AnchorProbeResult { reachable: false }

Asymmetric return path: If cold connect fails, by definition there is no direct path from C to A. C reports failure through B (who has a live connection to A). On success, C has a fresh direct connection and uses it. The return_via field tells C which node to route failure through.

Why bypass the cascade: The normal connect_by_node_id cascade has 7 steps including hole punch and relay. If C uses the full cascade, a successful result via relay is a false positive. The probe handler must be a special code path: raw QUIC connect only.

Anchor candidacy checklist

is_anchor_candidate():
  - has UPnP mapping OR has IPv6 public address
  - probe succeeded within last 30 minutes
  - mesh ≥ 50 peers (sufficient N2 density)
  - uptime ≥ 2 hours continuous
  - NOT mobile (platform check at build time)

Probe refresh schedule

Session fallback for full anchors

When an anchor's mesh is full (101/101), new nodes fall back to a session connection for matchmaking. The anchor accepts referral requests over session connections, not just mesh.

Remaining gaps

9. Referrals

Status: Complete

Referral list mechanics (anchor side)

Anchors maintain an in-memory HashMap of registered peers. Each entry: { node_id, addresses, use_count, disconnected_at }.

10. Relay & NAT Traversal

Status: Complete

Relay selection (find_relays_for)

Find up to 3 relay candidates, prioritized:

1. Preferred tree intersection: Target's preferred_tree (from social_routes, ~100 NodeIds) intersected with our connections. Prefer our own preferred peers within that tree. TTL=0.
2. N2 reporters: Our mesh peers who reported the target in their N1 share. TTL=0.
3. N3 via preferred tree: Target's preferred_tree intersected with N3 reporters. TTL=1.
4. N3 reporters: Any N3 reporter for the target. TTL=1.

RelayIntroduce flow (0xB0/0xB1)

1. Requester → opens bi-stream to relay, sends RelayIntroduce { target, requester, requester_addresses, ttl }
2. Relay handles three cases:
   • We ARE the target: Return our addresses, spawn hole punch to requester
   • Target is our mesh or session peer: Forward request to target on new bi-stream, relay response back. Inject observed public addresses for both parties (session peers carry remote_addr from their inbound connection).
   • TTL > 0 and target in our N2: Forward to the reporter with TTL-1 (chain forwarding, max TTL=2)
3. Requester receives RelayIntroduceResult { target_addresses, relay_available }, then:
   • hole_punch_parallel(): Try all returned addresses in parallel, retry every 2s, 30s total timeout
   • If hole punch fails and relay_available: open SessionRelay (0xB2) pipe through the intermediary

Session relay (relay pipes)

Intermediary splices bi-streams between requester and target. Desktop: max 10 concurrent pipes. Mobile: max 2. Each pipe has a 50MB byte cap and 2-min idle timeout.

Deduplication & cooldowns

Hole punch mechanics

Both sides filter self-reported addresses to publicly-routable only (no Docker bridge, VPN, or LAN IPs) and prepend UPnP external address if available. The relay injects each party's observed public address (from the QUIC connection) at the front of the list. All paths use hole_punch_parallel(): parse returned addresses into QUIC EndpointAddr, spawn parallel connect attempts to every address simultaneously. Each attempt: 2s timeout, retried until 30s total deadline. First successful connection wins.

NAT type detection

Status: Complete (interim: public STUN servers)

On startup, each node classifies its NAT type as one of four categories:

• Public — observed address matches local, or UPnP-mapped. Directly reachable.
• Easy — same mapped port from multiple probes (endpoint-independent mapping / cone NAT). Hole punch will likely succeed.
• Hard — different mapped ports per destination (symmetric / address-dependent mapping). Port is unpredictable.
• Unknown — detection failed or not yet run.

Current implementation (interim)

Raw STUN Binding Requests (20 bytes, no crate dependency) sent to stun.l.google.com:19302 and stun.cloudflare.com:3478 from a single UDP socket. XOR-MAPPED-ADDRESS parsed from each response (IPv4 + IPv6 supported). Comparison: same mapped port = Easy, different = Hard, matches local = Public. 3s timeout per server. UPnP success overrides to Public. Anchors skip probing entirely (already Public).

Target design (multi-anchor STUN)

When the network has enough anchors, replace public STUN servers with anchor-reported your_observed_addr from InitialExchange. Connecting to two or more anchors at different public IPs provides the same classification without external dependencies.

NAT type sharing

NAT type is included as a string field ("public"/"easy"/"hard"/"unknown") in InitialExchangePayload. Stored per-peer in the peers table (nat_type TEXT column). Available for hole punch decisions before any connection attempt.

Hole punch strategy

All hole punch paths use hole_punch_with_scanning() which replaces the former hard+hard skip. NAT profiles (NatMapping + NatFiltering) from InitialExchange determine whether scanning is attempted. Behavioral inference updates filtering classification from connection outcomes.

Advanced NAT traversal

Status: Complete

NAT "hardness" has two independent dimensions:

• Mapping: Endpoint-Independent Mapping (EIM / "easy") uses the same external port for all destinations. Endpoint-Dependent Mapping (EDM / "hard") assigns a different port per destination.
• Filtering: Address-restricted (Open) accepts from any port on an IP the host has sent to. Port-restricted accepts only from the exact IP:port the host has sent to.

STUN probing at startup classifies mapping (EIM/EDM). Filtering is determined reliably via the anchor filter probe.

NAT filter probe (0xC6/0xC7)

After anchor registration, each node with Unknown filtering sends a NatFilterProbe bi-stream request to its anchor. The anchor creates a temporary QUIC endpoint on a random port and attempts to connect to the node’s observed address (2s timeout). If the connection succeeds, the node is Open (address-restricted or better — accepts packets from any port on the anchor’s IP). If it times out, the node is PortRestricted.

This probe runs once at startup (during anchor register cycle) and the result feeds into all subsequent InitialExchange payloads, so peers know each other’s exact filtering type.

Note: “Public” NAT type does not automatically mean Open filtering. A node may be public on IPv6 but NATed on IPv4. The filter probe tests actual reachability from a different port, regardless of self-declared NAT type. Startup logs now report public (v4 only), public (v6 only), or public (v4+v6).

NAT combination matrix

Key insight: if both sides have Open (address-restricted) filtering, scanning is never needed — should_try_scanning() returns false and basic hole punch handles it.

Role-based scanning protocol

Each side independently determines its role based on its own NAT profile:

• EIM (stable port) → Puncher: Punch peer’s anchor-observed address every 2s. Our port is stable — the peer’s scanner will find us.
• EDM or Unknown → Scanner+Puncher: Walk outward from peer’s anchor-observed base port at ~100 ports/sec (base, base+1, base-1, base+2, base-2, ...). Each probe opens a firewall entry on our NAT. Also punch every 2s to check if peer has opened their port for us.

The scanner opens ports on its own firewall. The other side’s periodic punch (one every 2s to the scanner’s observed address) checks if the scanner has opened a port matching the puncher’s actual port. For both-EDM pairs, both sides scan and punch simultaneously.

Scan parameters

• Rate: ~100 ports/sec (one probe every 10ms)
• In-flight: ~20 concurrent (100/sec × 200ms connect timeout)
• Direction: Outward walk from anchor-observed base port
• Target address: Anchor-observed (relay-injected) address only — not VPN/cellular/LAN addresses
• Max duration: 5 minutes (covers full 65K port space at ~100/sec in ~11 minutes; ±2000 range covered in first 40 seconds)
• Task management: JoinSet with abort_all() on success or exhaustion — no orphaned tasks
• Punch interval: Every 2s to peer’s anchor-observed address

Why 5-minute scan duration is acceptable

The cost is time, not resources (~20 in-flight at any time, ~100 probes/sec). For connections that would otherwise be impossible (both EDM + port-restricted), accepting a longer setup time is far better than giving up entirely. Most successful connections resolve within the first 40 seconds (±2000 port range).

11. UPnP Port Mapping

Status: Complete

Purpose

UPnP (Universal Plug and Play) allows a node to request its home router to forward an external port to its local QUIC port. This makes the node directly reachable from the internet without hole punching — any peer with the external address can connect immediately. This dramatically improves connection success rates for desktop nodes on home networks.

Startup flow

bind Endpoint → attempt UPnP mapping (2s timeout) → store external addr → bootstrap

1. Discover gateway: Search for UPnP/NAT-PMP gateway with a 2-second timeout. If no gateway found, proceed without — do not block startup.
2. Request mapping: Map both UDP and TCP for the local QUIC port to the same external port (or next available). UDP is required for QUIC (existing). TCP enables HTTP post delivery (see Section 25). Both use the same external port number. If the router supports one but not the other, accept the partial mapping gracefully — QUIC connectivity is not affected by TCP mapping failure. Request lease TTL of 3600s.
3. Store external address: The resulting external SocketAddr is stored alongside iroh's observed addresses. It feeds into N+10 identification, InitialExchange, anchor registration, and all peer address advertisements.
4. Log result: Clearly log whether UPnP succeeded, failed, or was unavailable. This is critical for diagnosing connectivity issues.

Lease renewal cycle (every 2700s / 45 min)

UPnP mappings have a TTL (typically 3600s but varies by router). A renewal loop runs every 45 minutes to refresh the mapping before it expires. If renewal fails, the external address is removed from advertisements and the node falls back to hole punch / relay paths gracefully.

Shutdown

Explicitly release the UPnP mapping on clean shutdown. Routers have finite mapping tables — releasing is good citizenship. Tauri's shutdown hook handles this.

Integration with existing address logic

The UPnP external address is treated the same as any other address the node knows about. It feeds into:

• N+10 identification: Included in self-identification so peers store a routable address
• InitialExchange: Advertised to new connections
• Anchor registration: Included in bootstrap/recovery registration
• Social routing: Available in social route address cache for follows/audience
• Relay introduction results: Returned alongside hole-punch candidate addresses
• Share link host lists: The UPnP external address, when mapped for TCP, determines whether this node includes itself in share link host lists (see Section 26). A node only self-includes if it has confirmed TCP reachability — either via UPnP TCP mapping or a known public IPv6 address.

Why this matters for mobile

Mobile devices on cellular networks cannot use UPnP (carrier NAT doesn't expose it). However, if the peers they're trying to reach (especially desktop nodes and anchors) have UPnP mappings, those peers become directly reachable from the phone without hole punching. The phone doesn't need UPnP — the other side does.

Honest limitations

UPnP nodes are anchors

A node with a successful UPnP mapping is directly reachable from the internet — which is the only thing that makes an anchor an anchor. When UPnP mapping succeeds, the node self-declares as an anchor (is_anchor = true). Other peers will add it to their known_anchors table, providing diverse bootstrap paths back into the network.

When the UPnP mapping is lost (lease renewal fails, shutdown), the node reverts to non-anchor. Peers that stored it as an anchor will naturally age it out via last_seen — LIFO ordering means stale anchors drop to the bottom. The 7-day post-bootstrap cleanup probes stale entries and removes failures. No special cleanup needed beyond the existing anchor infrastructure.

This means any desktop on a home network with UPnP-capable router becomes a potential bootstrap point for the network, dramatically increasing the number of available anchors without any manual server deployment.

Implementation

Crate: igd-next (async support, well-maintained fork of igd). Implementation lives in network.rs alongside the iroh Endpoint — UPnP mapping is an Endpoint concern, not a connection concern.

12. LAN Discovery

Status: Planned

iroh's mDNS address lookup broadcasts peer presence on the local network via multicast DNS (service name "irohv1", backed by the swarm-discovery crate). Currently this is configured as a passive address resolver — if we already know a peer's NodeId, mDNS can resolve its LAN address. But mDNS also discovers unknown peers on the same network, and iroh exposes this via MdnsAddressLookup::subscribe().

Discovery flow

1. Hold the mDNS handle: Build MdnsAddressLookup explicitly (not via the endpoint builder) so we retain a clone for subscribing.
2. Spawn a LAN scan loop: Call mdns.subscribe().await to get a stream of DiscoveryEvent::Discovered and DiscoveryEvent::Expired events.
3. On discovery: Extract NodeId + LAN addresses from the event. If not already connected, initiate a direct connection + initial exchange. Register as a LAN session (a keep-alive session tagged as local).
4. On expiry: Clean up the LAN session. Peer left the network or powered off.

LAN sessions

LAN peers are special: zero-cost bandwidth, sub-millisecond latency, and very likely someone you know (same household/office). They deserve their own treatment beyond regular mesh or session slots:

• Automatic keep-alive: LAN sessions stay open as long as the peer is on the network (mDNS heartbeat). No idle timeout. Not counted against session slot limits.
• Sync priority: Pull sync and push notifications go to LAN peers first — instant delivery over the local link.
• Local relay: LAN peers can relay for each other to the wider internet. A phone behind carrier NAT can relay through the desktop's UPnP-mapped connection. Bandwidth is free (local network), so relay limits can be much more generous than over the internet.
• Blob transfer: Large blob transfers between LAN peers are essentially free. Prefer LAN peers as blob sources when available.

Design rationale

Today, two distsoc devices on the same WiFi network can only find each other if they happen to share a peer that reports them in N2. This is absurd — they're on the same network segment. LAN discovery turns mDNS from a passive address resolver into an active peer source, exploiting the fact that local bandwidth is essentially unlimited.

The keep-alive + relay pattern means a household with one well-connected desktop and several phones creates its own mini-mesh: the desktop provides anchor-like connectivity, the phones stay connected through it, and everyone syncs instantly over the LAN even when the internet connection drops.

13. Worm Search

Status: Complete

Used at step 4 of connect_by_node_id, after N2/N3 resolution fails.

Algorithm

1. Build needles: target NodeId + target's N+10 (up to 10 preferred peers from their profile/cached N+10)
2. Local check: Search own connections + N2/N3 for any of the 11 needles. Also check local storage, CDN downstream tree, and blob store for any requested post/blob content.
3. Burst (500ms timeout): Send WormQuery{ttl=0} (0x60) to all mesh peers in parallel. Each peer checks their local connections + N2/N3, plus local storage and CDN tree for post/blob content.
4. Nova (1.5s timeout): Each burst response includes a random "wide referral" — an N2 peer. Connect to those referrals and send WormQuery{ttl=1}. The referred peer does its own 101-burst (fans out to all its mesh peers with ttl=0). This reaches ~10K nodes with only ~202 relay hops, keeping network pressure low by expanding one hop at a time rather than flooding.
5. Total timeout: 3 seconds for the entire search.

Content search

WormQuery carries optional post_id and blob_id fields, enabling unified search for nodes, posts, and blobs in a single query. Each peer checks:

• Posts: local storage (direct match), CDN downstream tree (post_downstream — up to 100 known hosts per post)
• Blobs: local blob store, CDN post ownership (get_blob_post_id → post_downstream)

WormResponse carries post_holder and blob_holder fields alongside the existing node search results. A content hit (post or blob holder found) is treated as a successful response even without a node match.

The CDN layer is the key multiplier: each node's downstream tree can cover hundreds of posts across dozens of hosts, giving every peer thousands of "I know where that is" answers. Combined with social layer knowledge, even a 202-hop nova covers enormous content space.

PostFetch (0xD4/0xD5)

Lightweight single-post retrieval after worm search identifies a holder. Opens a bi-stream to the holder and requests one post by ID. Much lighter than full PullSync — no follow filtering, no batch processing, just the target post.

Dedup & cooldown

14. Preferred Peers

Status: Complete

Negotiation (MeshPrefer, 0xB3)

• Bilateral: Requester sends MeshPrefer{requesting: true}, responder accepts/rejects
• Acceptance: Both sides persist to preferred_peers table, upgrade slot to PeerSlotKind::Preferred
• Rejection reasons: "not connected", "preferred slots full (N/M)"

Properties

• Eviction-protected: Never evicted during rebalance (only non-preferred peers can be evicted)
• Priority reconnect: Reconnected first in rebalance (Priority 0), before any growth
• Pruned after 7 days unreachable: If a preferred peer can't be reached for 7 days, the slot is released. The bilateral agreement is cleared — reconnection requires a new MeshPrefer handshake. A reconnect watcher persists for 30 days at low priority (daily check). This prevents churn from aggressive pruning while ensuring slots aren't held indefinitely for offline peers.
• N+10 component: Your 10 preferred peers' NodeIds are included in your N+10 for all identification (see Section 3)
• Preferred tree: Each social route caches a preferred_tree (~100 NodeIds) — the target's preferred peers' preferred peers. Used for relay selection.

15. Social Routing

Status: Complete

Caches addresses for follows and audience members, separate from mesh connections.

social_routes table

Wire messages

Reconnect watchers

reconnect_watchers table: when peer A asks about disconnected peer B, A is registered as a watcher. When B reconnects, A gets a SocialAddressUpdate notification. Watchers pruned after 30 days. Low priority — daily check frequency for watchers older than 7 days.

Social route lifecycle

• Follow → store their N+10, upgrade to Mutual (if audience)
• Unfollow → downgrade/remove
• Approve audience → Mutual/Audience

16. Keep-Alive Sessions

Status: Planned

Purpose

When the mesh 101 doesn't provide <N4 access to all the nodes we need for social and file operations, keep-alive sessions bridge the gap. These are long-lived connections that participate in N2/N3 routing but are not part of the mesh 101.

Social/File connectivity check (every 60s)

Periodically check whether we can reach every node we need. A node is considered reachable if either:

• We have <N4 access to their N+10 (within N1/N2/N3), or
• There is an anchor within N2 of them — we can ask that anchor to matchmake on demand without maintaining a persistent connection

Only when neither condition is met do we open a keep-alive session. With UPnP auto-anchors (see Section 11) scattered throughout the network, the odds of an anchor being within N2 of any given peer increase significantly, reducing the number of keep-alive sessions needed.

Nodes to check:

• Nodes we DM'd in the last 4 hours
• All follows
• All audience members
• All file upstream peers (for blobs we host)
• All file downstream peers (for blobs we serve)

For any node whose N+10 is NOT reachable within N3, open a keep-alive session to the closest available node in their N+10 (or to them directly if possible). This ensures we can always find and reach our social and file contacts without worm search.

Keep-alive session behavior

• N2/N3 routing: Keep-alive sessions exchange N1/N2 diffs and participate in routing, similar to mesh connections. They expand our network knowledge without consuming mesh slots.
• Not counted in mesh 101: Keep-alive sessions are a separate pool. They don't affect mesh diversity scoring or slot management.
• Capacity limit: Max 50% of total session capacity is reserved for keep-alive sessions. The other 50% remains available for interactive sessions (DMs, group activity).
• Not idle-reaped: Unlike interactive sessions (5-min idle timeout), keep-alive sessions persist as long as the connectivity need exists.
• Reevaluated periodically: The 60s connectivity check closes keep-alive sessions that are no longer needed (e.g., the target now appears in N3 via a mesh connection).

Practical ceilings

Mobile priority stack

When approaching the mobile ceiling, keep-alive sessions are prioritized:

1. DMs last 30 min — active conversations take highest priority
2. Follows — people you follow
3. Audience — people following you
4. File peers — upstream/downstream blob hosts

Lower-priority sessions are closed first to make room.

Hysteresis

Don't open a keep-alive session for a contact who just barely fell outside N3. Wait for persistent unreachability — the contact must be absent from N1/N2/N3 for multiple consecutive connectivity checks (e.g., 3 checks = 3 minutes) before opening a keep-alive. This prevents churn from nodes that transiently appear and disappear at the N3 boundary.

Reject + redirect

When a node is at its keep-alive session capacity (50% of total sessions), it refuses new keep-alive requests with a redirect — offering a random N2 node that also has <N4 access to the target. Same pattern as mesh RefuseRedirect but for the keep-alive pool. The requester tries the suggested peer instead.

Cross-layer benefit

Keep-alive sessions from the social and file layers feed N2/N3 entries back into the mesh layer. A social keep-alive to a friend's preferred peer might provide N2 entries that help the mesh growth loop. Similarly, a file keep-alive to an upstream host might provide access to nodes the mesh has never seen. The three layers compound each other's reach.

17. Content Propagation

Intent

"Attention creates propagation": when you view something, you cache it. The cache is optionally offered for serving. Hot content spreads naturally through demand. Cold content decays unless intentionally hosted.

The CDN vision: every file by author X carries an author manifest with the author's N+10 and recent post list. If you hold any file by author X, you passively know X's recent posts and can find X through their N+10.

Status: Partial

• BlobRequest/BlobResponse (0x90/0x91) for peer-to-peer blob fetch
• AuthorManifest (ed25519-signed, 10+10 post neighborhood) travels with blob responses
• CDN hosting tree (1 upstream + 100 downstream per blob)
• ManifestPush propagates updates down the tree
• BlobDeleteNotice for tree healing on eviction
• Blob eviction with social-aware priority scoring

Passive discovery via neighborhood diffs

Passive file-chain propagation is enabled through BlobHeader neighborhood diffs. Every blob header carries the author's 25+25 post neighborhood (25 previous + 25 following). When a host receives a BlobHeaderDiff (0x96), they learn about the author's newer posts without explicit subscription. Hosts of old content are pulled toward new content by the same author naturally — attention creates propagation.

Remaining gaps

18. Files & Storage

Blob storage Complete

Blob content immutability

Blob data is BLAKE3-addressed — the CID is the hash of the content. This means blob content is immutable by definition. Any mutable metadata (neighborhood, host lists, signatures) MUST be stored separately in a BlobHeader. Inline mutable headers are architecturally incompatible with content addressing.

BlobHeader Planned

Formal mutable structure replacing/extending CdnManifest. Stored and transmitted separately from blob data.

BlobHeader {
    cid,                    // BLAKE3 hash of blob content
    author_nplus10,         // Author's N+10 (NodeId + 10 preferred peers)
    author_recent_posts,    // 25 previous + 25 following PostIds (neighborhood)
    upstream_nplus10,       // Upstream file source's N+10 (if not author)
    downstream_hosts,       // Up to min(100, floor(170MB / blob_size)) downstream hosts
    author_signature,       // ed25519 signature over author fields
    host_signature,         // ed25519 signature by current host
    updated_at,             // Timestamp of last header update
}

• Post neighborhood: 25 previous + 25 following PostIds. Forward slots are empty at publish time and populate via BlobHeaderDiff propagation as the author continues posting. Empty forward slots are not an error condition.
• Downstream host count: min(100, floor(170MB / blob_size_bytes)) — smaller blobs allow more downstream hosts, larger blobs reduce the count to cap per-host storage overhead.
• BlobHeaderRequest: Lightweight header-only fetch — retrieve just the header without retransferring blob data. Useful for neighborhood updates and host discovery.
• Self Last Encounter: Stored per-author, becomes the newer of what's stored and "file last update." Determines when to trigger pull sync.

Blob transfer flow (0x90/0x91)

1. Requester sends BlobRequest { cid, requester_addresses }
2. Host checks local BlobStore:
   • Has blob: Return base64-encoded data + CDN manifest + file header (N+10s, recent posts). Try to register requester as downstream (max 100). If full, return existing downstream as redirect candidates.
   • No blob: Return found: false
3. Requester verifies CID, stores blob locally, records upstream in blob_upstream table. Updates Self Last Encounter for the author based on file header.

CDN hosting tree Complete

• AuthorManifest: ed25519-signed by post author, contains post neighborhood (25 previous + 25 following posts — see BlobHeader above), author N+10, author addresses
• CdnManifest: AuthorManifest + hosting metadata (host NodeId/addresses, source, downstream count)
• Tree structure: Each blob has 1 upstream source + up to 100 downstream hosts
• ManifestPush (0x94): Author/admin pushes updated manifests downstream, which relay to their downstream
• ManifestRefreshRequest/Response (0x92/0x93): Check if manifest has been updated since last fetch
• BlobDeleteNotice (0x95): Notify tree when blob is deleted; includes upstream info for tree healing

Blob eviction Complete

priority = pin_boost + (relationship * heart_recency * freshness / (peer_copies + 1))

Pin modes Planned

The CDN is delivery infrastructure, not storage. Authors own durability. Pinning extends content in the local delivery pool — it is not a network obligation.

19. Sync Protocol

Wire format

[1 byte: MessageType] [4 bytes: length (big-endian)] [length bytes: JSON payload]

Max payload: 16 MB. ALPN: itsgoin/3.

Pull sync: social + file layers, not mesh

Self Last Encounter: For each peer we sync with, we track the timestamp of our last successful sync. When Self Last Encounter ages beyond 3 hours, a pull sync is triggered. Self Last Encounter is updated to the newer of: (a) what's currently stored, or (b) the "file last update" timestamp from file headers received during blob transfers. Since file headers include the author's recent post list, downloading a blob from any peer hosting that author's content can update Self Last Encounter for the author.

Pull sync filtering

• PullSyncRequest: Includes requester's follow list + post IDs they already have
• PullSyncResponse: Sender filters posts through should_send_post():
  1. Author is requester → always send (own posts relayed back)
  2. Public + author in requester's follows → send
  3. Encrypted + requester in wrapped key recipients → send
  4. Otherwise → skip

Message types (41 total)

Engagement propagation

Reactions, comments, and policy changes propagate via BlobHeaderDiff (0xD0) through the CDN tree:

• Push (real-time): On react/comment, the diff is sent to both downstream peers (CDN tree children) and the upstream peer (who we got the post from). Each intermediate node re-propagates both directions, excluding sender. This flows the diff up to the author and down to all holders.
• Auto downstream registration: Nodes that receive a post via pull sync or push notification automatically send PostDownstreamRegister (0xD3) to the sender, ensuring bidirectional diff flow.
• Pull (safety net): Every 5 minutes, the pull cycle requests BlobHeaderRequest (0xD1) with the local header timestamp. Peers respond with the full header only if theirs is newer. Additive merge — store_reaction upserts, store_comment inserts with ON CONFLICT DO NOTHING.
• Planned: Pull engagement from both upstream and downstream peers to catch missed diffs from either direction.

20. Encryption

Envelope encryption (1-layer) Complete

1. Generate random 32-byte CEK (Content Encryption Key)
2. Encrypt content: ChaCha20-Poly1305(plaintext, CEK, random_nonce)
3. Store as: base64(nonce[12] || ciphertext || tag[16])
4. For each recipient (including self):
   • X25519 DH: our_ed25519_private (as X25519) * their_ed25519_public (as montgomery)
   • Derive wrapping key: BLAKE3_derive_key("distsoc/cek-wrap/v1", shared_secret)
   • Wrap CEK: ChaCha20-Poly1305(CEK, wrapping_key, random_nonce) → 60 bytes per recipient

Visibility variants

PostId integrity

PostId = BLAKE3(Post) covers the ciphertext, NOT the recipient list. Visibility is separate metadata. This means visibility can be updated (re-wrapped) without changing the PostId.

Group keys (circles) Complete

• Each circle gets its own ed25519 keypair
• group_id = BLAKE3(initial_public_key) — permanent identifier
• Group seed wrapped per-member via X25519 DH (KDF domain: "distsoc/group-key-wrap/v1")
• Epoch rotation: On member removal, generate new keypair, increment epoch, re-wrap for remaining members
• Wire: GroupKeyDistribute (0xA0), GroupKeyRequest/Response (0xA1/0xA2)

Three-tier access revocation

Three levels of revocation, chosen based on threat level:

Private profiles (Phase D-4) Complete

Different profile versions per circle, encrypted with the circle/group key. A peer sees the profile version for the most-privileged circle they belong to. CircleProfileUpdate (0xB4) wire message. Public profiles can be hidden (public_visible=false strips display_name/bio).

21. Delete Propagation

Status: Complete

Delete records

DeleteRecord { post_id, author, timestamp_ms, signature } — ed25519-signed by author. Stored in deleted_posts table (INSERT OR IGNORE). Applied: DELETE from posts table WHERE post_id AND author match.

Propagation paths

1. InitialExchange: All delete records exchanged on connect
2. DeleteRecord message (0x51): Pushed via uni-stream to connected peers on creation
3. PullSync: Included in responses for eventual consistency

CDN cascade on delete

1. Send BlobDeleteNotice to all downstream hosts (with our upstream info for tree healing)
2. Send BlobDeleteNotice to upstream
3. Clean up blob metadata, manifests, downstream/upstream records
4. Delete blob from filesystem

22. Social Graph Privacy

Status: Complete

• Follows are never shared in gossip or profiles
• N1 share merges mesh peers + social contacts into one list (indistinguishable)
• No addresses ever shared in routing updates
• N3 is never shared outward (search-only)

23. Multi-Device Identity

Status: Planned

Concept

Multiple devices share the same identity key (ed25519 keypair, same NodeId). All devices ARE the same node from the network's perspective. Posts from any device appear as the same author.

Device identity

Each device also generates a unique device identity (separate ed25519 keypair). This device-specific key is used to:

• Find each other: Devices with the same shared identity can search for each other using their device identities to facilitate syncs and self-routing
• Own-device relay: Route traffic through your own devices (e.g., home computer relaying for your phone) using the device identity for authentication
• Conflict resolution: When devices post simultaneously, device identity helps order and deduplicate

Setup

Export identity.key from one device, import on another. The device identity is generated automatically on each device. Once two devices share an identity key, they can discover each other through normal network routing (same NodeId appears at multiple addresses).

24. Phase 2: Reciprocity (Reconsidered)

Status: Reconsidered

The original Phase 2 design centered on hosting quotas (3x rule), chunk audits, and tit-for-tat QoS. On reflection, the attention-driven delivery model makes quota enforcement unnecessary. The CDN is a delivery amplifier, not a storage system — hot content propagates through demand, cold content decays. Authors are responsible for their own content durability.

Tit-for-tat QoS solves the wrong problem: it optimizes for fairness in a storage-obligation model that no longer exists. What matters is that the delivery network functions efficiently, which it does through natural attention dynamics.

If reciprocity mechanisms are needed at scale, they should address delivery quality (bandwidth, latency, uptime) rather than storage quotas. This remains an open design area.

25. HTTP Post Delivery

Intent

Every ItsGoin node that is publicly reachable can serve its cached public posts directly to browsers over HTTP — no extra infrastructure, no additional dependencies, no new binary. The same QUIC UDP port used for app traffic is accompanied by a TCP listener on the same port number. UDP goes to the QUIC stack as always. TCP goes to a minimal raw HTTP/1.1 handler baked into the binary.

This makes every publicly-reachable node a browser-accessible content endpoint, enabling share links that deliver content peer-to-browser without routing any post bytes through itsgoin.net.

Dual listener architecture

<port>/UDP  →  QUIC (existing app protocol)
<port>/TCP  →  HTTP/1.1 (new, read-only, single route)

Both listeners bind on the same port. The OS routes UDP and TCP to separate sockets — no conflict, no protocol ambiguity.

HTTP handler

The handler is intentionally minimal — implemented with raw tokio::net::TcpListener, no HTTP crate, no new dependencies. Approximately 150–200 lines of Rust.

Single valid route: GET /p/<postid_hex> HTTP/1.1

• postid_hex must be exactly 64 lowercase hex characters (BLAKE3 hash)
• Any other path, method, or malformed request: hard close with no response (not even a 400). Do not be helpful to malformed requests.
• Post must be public (PostVisibility::Public). Encrypted posts are never served over HTTP regardless of whether the node holds the content.

Response: Minimal HTML page containing the post content with a small footer:

<footer>
  This post is on the ItsGoin network — content lives on people's devices,
  not servers. <a href="https://itsgoin.com">Get ItsGoin</a>
</footer>

The footer HTML is a static string constant compiled into the binary (~2KB). No template engine, no dynamic footer generation.

Security constraints

Which nodes serve HTTP

A node serves HTTP only if it is publicly TCP-reachable:

• IPv6 public address — serves directly
• IPv4 + UPnP mapping — serves if TCP is included in the UPnP mapping (see Section 11 update)
• IPv4 behind NAT without UPnP — cannot serve HTTP, but can still appear as a host in share links for app-protocol delivery. The CDN tree and itsgoin.net redirect handler route around unreachable nodes automatically.

302 load shedding via CDN tree

When a node is overwhelmed (at the 20-connection cap) or chooses to redirect:

1. Query post_downstream table for the requested postid
2. Filter downstream hosts to those with a known public address (IPv6 or UPnP-mapped IPv4)
3. 302 → http://[their_address]:<port>/p/<postid>

The receiving node applies the same logic recursively if needed. This mirrors the app-layer CDN tree behavior at the HTTP layer — the same attention-driven propagation model, the same tree structure, now accessible to browsers.

Binary size impact

Zero new dependencies. Negligible compiled size delta (~10–20KB). No App Store size concerns. No install size impact for existing users.

26. Share Links

Intent

Every public post can be shared as a URL that works for both app users and browser users:

• App installed: OS intercepts the URL via Universal Links (iOS) / App Links (Android) before the browser loads. App opens directly to the post, fetched via QUIC. Zero browser involvement.
• No app: Browser loads itsgoin.net, which searches the ItsGoin network for the post and redirects the browser to a live node serving it over HTTP. The share link becomes a product demo and install opportunity.

URL format

https://itsgoin.net/p/<postid_hex>/<encoded_hostlist>

• postid_hex: 64 hex characters (BLAKE3 post hash)
• encoded_hostlist: base64url-encoded binary list of up to 5 host entries (see encoding below)

Example: https://itsgoin.net/p/3a7f...c921/AAEC...Zg==

Host list encoding

Compact binary encoding — optimized for QR code scanability:

Per IPv6 host:  [0x06][16 bytes IP][2 bytes port]  =  19 bytes
Per IPv4 host:  [0x04][4 bytes IP][2 bytes port]   =   7 bytes

5× IPv6:  95 bytes → ~127 chars base64url  (comfortably scannable QR)

All integers big-endian. base64url-encoded (URL-safe, no padding).

Host list generation (at share time)

When a user taps “Share” on a post:

1. Query post_downstream for this postid
2. Filter to hosts with a known public address (IPv6 or UPnP-mapped IPv4)
3. Select up to 5 — prefer IPv6 public over UPnP IPv4, prefer most recently seen over stale
4. Include self if this node is publicly reachable
5. Encode and embed in URL

Availability math

At 80% per-node uptime (conservative for a mix of home and mobile nodes), 5 independent hosts gives 1 - (0.2⁵) = 99.97% link availability. Hosts are selected from nodes that have already demonstrated they cached this specific post — not random peers.

itsgoin.net QUIC proxy handler

Route: GET /p/<postid_hex>/<author_nodeid_hex>

1. Check local storage (fast path — post already fetched recently)
2. Connect to author via QUIC (connect_by_node_id cascade) → PostFetch
3. Content search (extended worm with post_id) → find holder → PostFetch
4. Found? Store temporarily + render HTML + serve to browser
5. Not found? Serve "unavailable" page

The itsgoin.net server acts as a QUIC proxy — it fetches posts on-demand from the peer network and renders them as HTML for the browser. Posts are not permanently stored on the server. This is a marketing/convenience service, not a data store. The proxy model works because most nodes are behind NAT and can't serve HTTP directly to browsers.

Scalable via additional instances: 1.itsgoin.net, 2.itsgoin.net, etc. Each runs its own ItsGoin node with its own mesh connections, increasing total search coverage.

itsgoin.net node

itsgoin.net runs a permanent, well-connected ItsGoin node (--bind 0.0.0.0:4433 --daemon --web 8080). This serves two purposes:

1. Content search — when a share link is visited, the server-side node uses the extended worm search (with post_id) to find any peer holding the post. The CDN tree means each peer knows about hundreds of posts across their downstream hosts, making hits highly likely even for content the server has never synced.
2. Anchor — a permanently-online, high-uptime node that bootstrap peers can rely on. Strengthens the network’s anchor infrastructure without any special protocol — it’s just a well-connected peer that happens to also serve the web handler.

Share link format

https://itsgoin.net/p/<postid_hex>/<author_nodeid_hex>

• PostID: 64 hex chars (32 bytes, BLAKE3 content hash)
• Author NodeID: 64 hex chars (32 bytes, ed25519 public key)
• Author ID enables direct QUIC connection as fast path; worm search handles the case where author is unreachable
• Only public posts can generate share links

Unavailable page

⬡ This content isn't currently reachable.

  It may be available again when someone
  who has it comes back online.

  [ Install ItsGoin to find it when it resurfaces ]

This is not a 404. It communicates the honest model: content lives on devices, not servers. Cold content decays. The install CTA is the honest answer to “how do I get this.”

Universal Links / App Links

Same URL — itsgoin.net/p/... — intercepts to the native app for users who have ItsGoin installed. No separate URL scheme, no app:// links.

Required static files on itsgoin.net:

/.well-known/apple-app-site-association     (iOS Universal Links)
/.well-known/assetlinks.json                (Android App Links)

Both are static JSON deployed once, pointing to the ItsGoin app package ID for the path pattern /p/*.

App-side handling: Register the URL pattern in Tauri config. On receipt of itsgoin.net/p/<postid>/<hostlist>, parse the postid, decode the hostlist, fetch via QUIC from the hostlist peers. If the post is already in local SQLite, render immediately. Universal Links intercept before the browser loads — itsgoin.net sees zero traffic for app users.

iOS caveat: Universal Links require the app to have been opened manually at least once before OS interception activates. First-time tap from a link goes to the browser fallback. All subsequent taps open the app directly. The browser fallback is the full loading screen experience — first-time users see the product demo, which is the right outcome anyway.

QR codes

Share links are also valid QR codes. At ~127 chars base64url for 5 IPv6 hosts plus postid and domain, total URL length stays well under 200 characters — comfortably scannable at low error correction.

QR codes for share links use the same Universal Links / App Links interception path. A generic phone camera scanning the QR sees an itsgoin.net URL and offers to open it — either in the app (if installed) or in the browser.

No custom QR scheme needed. The HTTPS URL is the QR payload.

Chrome HTTPS (October 2026)

Chrome 154 (October 2026) enables “Always Use Secure Connections” by default, warning before HTTP sites. This does not affect the share link architecture:

• itsgoin.net is HTTPS — no warning, Universal Links work normally
• The 302 redirect takes the browser off the HTTPS page before content loads, so no mixed-content issue
• Node HTTP endpoints are raw IP:port addresses, which Chrome treats as private network addresses (exempt from the public-site warning requirement)
• The redirect itself is a header only — no content flows through itsgoin.net

No architecture changes needed before or after October 2026.

Appendix A: Timeout Reference

Appendix B: Design Constraints

Appendix C: Implementation Scorecard

Appendix D: Critical Path Forward

The highest-impact items, in priority order:

Appendix E: Features Designed But Not Built

Appendix F: File Map

crates/core/
  src/
    lib.rs          — module registration, parse_connect_string, parse_node_id_hex
    types.rs        — Post, PostId, NodeId, PublicProfile, PostVisibility, WrappedKey,
                      VisibilityIntent, Circle, PeerRecord, Attachment
    content.rs      — compute_post_id (BLAKE3), verify_post_id
    crypto.rs       — X25519 key conversion, DH, encrypt_post, decrypt_post, BLAKE3 KDF
    blob.rs         — BlobStore, compute_blob_id, verify_blob
    storage.rs      — SQLite: posts, peers, follows, profiles, circles, circle_members,
                      mesh_peers, reachable_n2/n3, social_routes, blobs, group_keys,
                      preferred_peers, known_anchors; auto-migration
    protocol.rs     — MessageType enum (39 types), ALPN (itsgoin/3),
                      length-prefixed JSON framing, read/write helpers
    connection.rs   — ConnectionManager + ConnHandle/ConnectionActor (actor pattern):
                      mesh QUIC connections (MeshConnection), session connections,
                      slot management, initial exchange, N1/N2 diff broadcast,
                      pull sync, relay introduction. All external access via ConnHandle.
    network.rs      — iroh Endpoint, accept loop, connect_to_peer,
                      connect_by_node_id (7-step cascade), mDNS discovery
    node.rs         — Node struct (ties identity + storage + network), post CRUD,
                      follow/unfollow, profile CRUD, circle CRUD, encrypted post creation,
                      startup cycles, bootstrap, anchor register cycle
    web.rs          — itsgoin.net web handler: QUIC proxy for share links,
                      on-demand post fetch via content search, blob serving
    http.rs         — HTML rendering for shared posts (render_post_html)

crates/cli/
  src/main.rs       — interactive REPL + anchor mode (--bind, --daemon, --web)

crates/tauri-app/
  src/lib.rs        — Tauri v2 commands (38 IPC handlers), DTOs

frontend/
  index.html        — single-page UI: 5 tabs (Feed / My Posts / People / Messages / Settings)
  app.js            — Tauri invoke calls, rendering, identicon generator, circle CRUD
  style.css         — dark theme, post cards, visibility badges, transitions

License

ItsGoin is released under the Apache License, Version 2.0. You may use, modify, and distribute this software freely under the terms of that license.

This is a gift. Use it well.