invites: add invite links for automatic peer acceptance

An invite link in format `awl://invite?p=<peer_id>&t=<token>&n=<name>`.
Whoever presents the token is added without a manual accept, with
the alias and exit node permission the creator chose when making the link.
Links are single-use and expire in a day by default, and can be revoked; the
token is optional, and without it the link is just the shareable form of a
peer id (that is what `awl cli me id` now prints and puts in its QR).

The invite itself lives in the creator's config, so nothing but the token and a
display name travels in the link, revoking really closes it, and the receiver
can add the creator while it is still offline. A use is spent inside the same
critical section that writes the peer it pays for, so a spent use and an added
peer can never come apart — hence ReserveInviteUnlocked, called from AddPeer
and from the UpdatePeerFields mutator rather than reserved and rolled back.

A token that no longer works degrades into an ordinary auth request for a manual accept.
Blocking still outranks an invite.

Adds config.Invite + Config.Invites, KnownPeer.InviteID (creator's marker) and
KnownPeer.PendingInviteToken (receiver's secret, presented until confirmed and
restored after a restart), the Go link parser in entity/invite_link.go, the
peers/invites/{create,list,revoke} endpoints, awlevent.InviteRedeemed and two
metrics. CLI and GUI come separately.

Author: pymq

api/api.go

@@ -150,6 +150,9 @@ func (h *Handler) setupRouter(address string) (*echo.Echo, error) {
 	e.POST(RemovePeerSettingsPath, h.RemovePeer)
 	e.GET(GetAuthRequestsPath, h.GetAuthRequests)
 	e.GET(GetBlockedPeersPath, h.GetBlockedPeers)
+	e.POST(CreateInvitePath, h.CreateInvite)
+	e.GET(GetInvitesPath, h.GetInvites)
+	e.POST(RevokeInvitePath, h.RevokeInvite)
 
 	// Settings
 	e.GET(GetMyPeerInfoPath, h.GetMyPeerInfo)

api/apiclient/client.go

@@ -116,6 +116,29 @@ func (c *Client) AuthRequests() ([]entity.AuthRequest, error) {
 	return authRequests, nil
 }
 
+func (c *Client) CreateInvite(request entity.CreateInviteRequest) (*entity.InviteResponse, error) {
+	invite := new(entity.InviteResponse)
+	err := c.sendPostRequest(api.CreateInvitePath, request, invite)
+	if err != nil {
+		return nil, err
+	}
+	return invite, nil
+}
+
+func (c *Client) Invites() ([]entity.InviteResponse, error) {
+	invites := make([]entity.InviteResponse, 0)
+	err := c.sendGetRequest(api.GetInvitesPath, &invites)
+	if err != nil {
+		return nil, err
+	}
+	return invites, nil
+}
+
+func (c *Client) RevokeInvite(id string) error {
+	request := entity.RevokeInviteRequest{ID: id}
+	return c.sendPostRequest(api.RevokeInvitePath, request, nil)
+}
+
 func (c *Client) BlockedPeers() ([]config.BlockedPeer, error) {
 	blocked := make([]config.BlockedPeer, 0)
 	err := c.sendGetRequest(api.GetBlockedPeersPath, &blocked)

api/const.go

@@ -15,6 +15,11 @@ const (
 	AcceptPeerInvitationPath = V0Prefix + "peers/accept_peer"
 	GetAuthRequestsPath      = V0Prefix + "peers/auth_requests"
 
+	// Invite links
+	CreateInvitePath = V0Prefix + "peers/invites/create"
+	GetInvitesPath   = V0Prefix + "peers/invites/list"
+	RevokeInvitePath = V0Prefix + "peers/invites/revoke"
+
 	// Settings
 	GetMyPeerInfoPath        = V0Prefix + "settings/peer_info"
 	UpdateMyInfoPath         = V0Prefix + "settings/update"

api/invites.go

@@ -0,0 +1,145 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/labstack/echo/v4"
+
+	"github.com/anywherelan/awl/config"
+	"github.com/anywherelan/awl/entity"
+)
+
+const defaultInviteMaxUses = 1
+
+// @Tags		Peers
+// @Summary	Create an invite link
+// @Accept		json
+// @Produce	json
+// @Param		body	body		entity.CreateInviteRequest	true	"Params"
+// @Success	200		{object}	entity.InviteResponse
+// @Failure	400		{object}	api.Error
+// @Failure	500		{object}	api.Error
+// @Router		/peers/invites/create [POST]
+func (h *Handler) CreateInvite(c echo.Context) (err error) {
+	req := entity.CreateInviteRequest{}
+	err = c.Bind(&req)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, ErrorMessage(err.Error()))
+	}
+	if err = c.Validate(req); err != nil {
+		return c.JSON(http.StatusBadRequest, ErrorMessage(err.Error()))
+	}
+
+	if req.MaxUses == 0 {
+		req.MaxUses = defaultInviteMaxUses
+	}
+	req.Alias = strings.TrimSpace(req.Alias)
+	// One alias cannot name several peers, so it only makes sense for a
+	// single-use link. Uniqueness itself is not checked here: the peer list will
+	// have moved on by the time the link is redeemed, and a collision is
+	// resolved then (GenUniqPeerAlias), so checking now would only produce
+	// false rejections.
+	if req.Alias != "" && req.MaxUses != 1 {
+		return c.JSON(http.StatusBadRequest,
+			ErrorMessage("alias can only be set for a single-use invite"))
+	}
+
+	var expiresAt time.Time
+	if req.ExpiresInSeconds > 0 {
+		expiresAt = time.Now().Add(time.Duration(req.ExpiresInSeconds) * time.Second)
+	}
+
+	invite, err := h.conf.CreateInvite(config.CreateInviteParams{
+		Label:                req.Label,
+		Alias:                req.Alias,
+		AllowUsingAsExitNode: req.AllowUsingAsExitNode,
+		MaxUses:              req.MaxUses,
+		ExpiresAt:            expiresAt,
+	})
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, ErrorMessage(err.Error()))
+	}
+
+	return c.JSON(http.StatusOK, h.inviteResponse(invite))
+}
+
+// @Tags		Peers
+// @Summary	Get invite links
+// @Accept		json
+// @Produce	json
+// @Success	200	{array}	entity.InviteResponse
+// @Router		/peers/invites/list [GET]
+func (h *Handler) GetInvites(c echo.Context) (err error) {
+	invites := h.conf.ListInvites()
+
+	result := make([]entity.InviteResponse, 0, len(invites))
+	for _, invite := range invites {
+		result = append(result, h.inviteResponse(invite))
+	}
+
+	return c.JSON(http.StatusOK, result)
+}
+
+// @Tags		Peers
+// @Summary	Revoke an invite link
+// @Description Stops new connections through the link; peers already added stay.
+// @Accept		json
+// @Produce	json
+// @Param		body	body	entity.RevokeInviteRequest	true	"Params"
+// @Success	200		"OK"
+// @Failure	400		{object}	api.Error
+// @Failure	404		{object}	api.Error
+// @Router		/peers/invites/revoke [POST]
+func (h *Handler) RevokeInvite(c echo.Context) (err error) {
+	req := entity.RevokeInviteRequest{}
+	err = c.Bind(&req)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, ErrorMessage(err.Error()))
+	}
+	if err = c.Validate(req); err != nil {
+		return c.JSON(http.StatusBadRequest, ErrorMessage(err.Error()))
+	}
+
+	if !h.conf.RevokeInvite(req.ID) {
+		return c.JSON(http.StatusNotFound, ErrorMessage("invite not found"))
+	}
+
+	return c.NoContent(http.StatusOK)
+}
+
+// inviteResponse renders an invite for the API, building the link from our
+// current peer ID and node name.
+func (h *Handler) inviteResponse(invite config.Invite) entity.InviteResponse {
+	h.conf.RLock()
+	peerID := h.conf.P2pNode.PeerID
+	nodeName := h.conf.P2pNode.Name
+	h.conf.RUnlock()
+
+	return entity.InviteResponse{
+		ID:                   invite.ID,
+		Label:                invite.Label,
+		Link:                 entity.BuildInviteLink(peerID, invite.Token, nodeName),
+		Alias:                invite.Alias,
+		AllowUsingAsExitNode: invite.WeAllowUsingAsExitNode,
+		MaxUses:              invite.MaxUses,
+		UsedCount:            invite.UsedCount,
+		ExpiresAt:            invite.ExpiresAt,
+		CreatedAt:            invite.CreatedAt,
+		Revoked:              invite.Revoked,
+		Status:               inviteStatus(invite),
+	}
+}
+
+func inviteStatus(invite config.Invite) string {
+	switch {
+	case invite.Revoked:
+		return entity.InviteStatusRevoked
+	case invite.IsExpired(time.Now()):
+		return entity.InviteStatusExpired
+	case invite.IsUsedUp():
+		return entity.InviteStatusUsedUp
+	}
+	return entity.InviteStatusActive
+}

api/peers.go

@@ -57,6 +57,7 @@ func (h *Handler) getKnownPeers() []entity.KnownPeersResponse {
 			WeAllowUsingAsExitNode:        knownPeer.WeAllowUsingAsExitNode,
 			AllowedUsingAsExitNode:        knownPeer.AllowedUsingAsExitNode,
 			RemoteVPNGatewayServerEnabled: knownPeer.RemoteVPNGatewayServerEnabled,
+			InviteID:                      knownPeer.InviteID,
 			LastSeen:                      knownPeer.LastSeen,
 			Connections:                   h.p2p.PeerConnectionsInfo(id),
 			NetworkStats:                  netStats,
@@ -188,6 +189,7 @@ func (h *Handler) SendFriendRequest(c echo.Context) (err error) {
 		Alias:                req.Alias,
 		IPAddr:               req.IPAddr,
 		AllowUsingAsExitNode: req.AllowUsingAsExitNode,
+		PendingInviteToken:   req.Token,
 	})
 	if err != nil {
 		return c.JSON(http.StatusBadRequest, ErrorMessage(err.Error()))

api_handlers_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/anywherelan/awl/api"
 	"github.com/anywherelan/awl/config"
@@ -130,6 +131,89 @@ func TestAcceptFriend_ErrorCases(t *testing.T) {
 	})
 }
 
+// TestInvitesAPI covers the invite link lifecycle through the API alone:
+// creating a link, seeing it in the list and revoking it. Redeeming one takes
+// two nodes and lives in application_test.go (TestAddPeerViaInviteLink and
+// around it).
+func TestInvitesAPI(t *testing.T) {
+	ts := NewTestSuite(t)
+
+	peer1 := ts.NewTestPeer(false)
+	err := peer1.api.UpdateMySettings("alice")
+	ts.NoError(err)
+
+	invites, err := peer1.api.Invites()
+	ts.NoError(err)
+	ts.Len(invites, 0)
+
+	created, err := peer1.api.CreateInvite(entity.CreateInviteRequest{
+		Label:                "my laptop",
+		Alias:                "laptop",
+		AllowUsingAsExitNode: true,
+		ExpiresInSeconds:     int64((24 * time.Hour).Seconds()),
+	})
+	ts.NoError(err)
+	ts.Equal(1, created.MaxUses, "MaxUses defaults to single-use")
+	ts.Equal(0, created.UsedCount)
+	ts.Equal(entity.InviteStatusActive, created.Status)
+	ts.True(created.AllowUsingAsExitNode)
+	ts.False(created.Revoked)
+	ts.WithinDuration(time.Now().Add(24*time.Hour), created.ExpiresAt, time.Minute)
+
+	link, err := entity.ParseInviteLink(created.Link)
+	ts.NoError(err)
+	ts.Equal(peer1.PeerID(), link.PeerID)
+	ts.Equal("alice", link.Name)
+	ts.NotEmpty(link.Token)
+
+	// The token only ever leaves through the link, never as a field of its own.
+	withoutLink := *created
+	withoutLink.Link = ""
+	body, err := json.Marshal(withoutLink)
+	ts.NoError(err)
+	ts.NotContains(string(body), link.Token)
+
+	invites, err = peer1.api.Invites()
+	ts.NoError(err)
+	ts.Len(invites, 1)
+	ts.Equal(*created, invites[0])
+
+	err = peer1.api.RevokeInvite(created.ID)
+	ts.NoError(err)
+
+	invites, err = peer1.api.Invites()
+	ts.NoError(err)
+	ts.Len(invites, 1)
+	ts.True(invites[0].Revoked, "revoked invites stay in the list as history")
+	ts.Equal(entity.InviteStatusRevoked, invites[0].Status)
+
+	err = peer1.api.RevokeInvite("00000000")
+	ts.Error(err)
+	ts.ErrorContains(err, "invite not found")
+}
+
+func TestCreateInvite_ErrorCases(t *testing.T) {
+	ts := NewTestSuite(t)
+
+	peer1 := ts.NewTestPeer(false)
+
+	t.Run("AliasWithMultiUse", func(t *testing.T) {
+		_, err := peer1.api.CreateInvite(entity.CreateInviteRequest{MaxUses: 5, Alias: "laptop"})
+		ts.Error(err)
+		ts.ErrorContains(err, "alias can only be set for a single-use invite")
+	})
+
+	t.Run("TooManyUses", func(t *testing.T) {
+		_, err := peer1.api.CreateInvite(entity.CreateInviteRequest{MaxUses: 1000})
+		ts.Error(err)
+	})
+
+	t.Run("NegativeExpiry", func(t *testing.T) {
+		_, err := peer1.api.CreateInvite(entity.CreateInviteRequest{ExpiresInSeconds: -1})
+		ts.Error(err)
+	})
+}
+
 func TestRemovePeer_PeerNotFound(t *testing.T) {
 	ts := NewTestSuite(t)