Use portal-tunnel as BiBeam’s discovery bootstrap/publication layer

[gosunuts]

Summary

This issue proposes a clear architectural boundary for using portal-tunnel with BiBeam.

In this role, Portal would provide the public website and bootstrap surface that users reach first. It can publish coordinator endpoints, distribute bootstrap artifacts, expose NAT-behind coordinators over HTTPS/WSS, and optionally handle sign-in, subscription, or future x402-style payment flows.

BiBeam itself would keep the native coordinator flow and remain authoritative for admission.

Why Portal?

A normal hosted website would be enough if we only needed a static landing page, documentation, and download links. Portal becomes useful when BiBeam needs a dynamic, operator-controlled public edge. It lets operators expose BiBeam from NAT-hidden environments such as homelabs, private servers, or laptops, without requiring a public IP or separate public-facing infrastructure.

With Portal, BiBeam can:

• serve the browser-facing entrypoint that users reach first
• distribute BiBeam client binaries, bootstrap artifacts, and coordinator metadata from the same public surface
• expose coordinators and bootstrap services even when they live behind NAT or private infrastructure
• publish and rotate public-facing hostnames more flexibly than a single fixed web deployment
• use multiple relays and multiple public entrypoints instead of concentrating discovery on one host, one provider, or one static domain
• make the bootstrap and onboarding surface more censorship-resistant by separating the public entry layer from the coordinator’s physical location
• combine onboarding, sign-in, subscription, and payment UX with dynamic coordinator exposure under one operator-owned system

In other words, Portal is valuable not just because it can host a website, but because it can act as a dynamic publication and distribution layer for BiBeam: one that supports flexible domains, relay-backed exposure, and a more censorship-resistant public entrypoint for discovery and onboarding.

Proposed model

Portal is responsible for

• the public web entrypoint for users
• distributing BiBeam client binaries
• onboarding and storefront UX
• publishing coordinator URLs and coordinator metadata
• distributing bootstrap artifacts
• optionally gating bootstrap access behind login or payment
• optionally exposing a NAT-behind coordinator’s native HTTPS/WSS surface

BiBeam coordinator remains responsible for

• register
• match
• heartbeat
• disconnect
• invite verification
• session-token issuance
• exit / cohort / forwarder binding
• final admission decisions

Suggested flow

1. A user lands on a browser-accessible Portal website
2. Portal presents onboarding, pricing, sign-in, and optional payment UX
3. After that step succeeds, Portal returns a bootstrap artifact
4. The client uses that artifact to start the native BiBeam bootstrap flow
5. The coordinator verifies the artifact and decides whether to admit the client

Bootstrap artifact

The bootstrap artifact may include:

• coordinator URLs
• coordinator public-key metadata or fingerprints
• public UDP endpoint hints
• a short-lived signed invite or another coordinator-verifiable admission artifact

The signed-invite path seems like the best fit for the current BiBeam bootstrap flow.

Why this is a good boundary

This keeps responsibilities clean:

• Portal handles publication, onboarding, and storefront concerns
• BiBeam handles discovery semantics and admission
• WireGuard remains direct UDP transport
• payment and account logic stay in the control-plane/web layer
• the VPN packet path stays free of storefront logic

Out of scope

This proposal does not mean:

• replacing BiBeam’s native discovery protocol
• making Portal the source of truth for session admission
• relaying WireGuard packets through Portal
• relaying STUN traffic through Portal
• relaying BiBeam forwarder traffic through Portal
• enforcing payment inside the WireGuard handshake
• enforcing payment in per-packet data-plane processing

Open question

What should the admission artifact be after login or payment?

Likely options:

• a short-lived signed invite
• a coordinator-verifiable payment receipt presented at register

The signed-invite approach appears to fit the current design best.

How should BiBeam’s deployment model change?

This includes whether the project should explicitly support Portal-backed onboarding/bootstrap surfaces running from NAT-hidden environments such as homelabs, private servers, or laptops, while keeping separate deployment requirements for exit and forwarder/data-plane nodes.