kolo docsbeta

Convide alguém para um grupo, em um programa de terminal

Um guia passo a passo. Um membro cria um código de convite, alguém entra com ele, e o membro aprova, recusa ou revoga.

Nesta página

Um grupo precisa de um jeito de deixar alguém novo entrar. Com a kolo-invite, um membro cria um código de convite e envia para a pessoa, em um chat ou em uma mensagem. Essa pessoa roda o app com o código, o membro vê o pedido e responde sim ou não, e o novo membro recebe o que precisa para encontrar o grupo.

Neste guia, você escreve um programa pequeno e roda esse programa duas vezes: como a Alice, que cria um grupo, e como o Bob, que entra nele. Depois você testa uma recusa, uma revogação e uma expiração. Tudo fica no seu computador, no endereço 127.0.0.1, com um nó de bootstrap em um terceiro terminal.

1Confira o que você precisa

Você precisa do Go 1.26 ou mais recente e de quatro janelas de terminal. Construa um chat no seu terminal mostra como instalar o Go. Abra as quatro janelas e deixe uma ao lado da outra:

Abra o app Terminal e aperte Cmd+N três vezes para ter mais três janelas.

Aqui o Terminal 1 roda o nó de bootstrap, o Terminal 2 roda a Alice, o Terminal 3 roda o Bob e o quarto terminal roda as pessoas que tentam entrar depois.

2Crie um módulo e baixe as bibliotecas

No Terminal 2, crie uma pasta para o programa e entre nela:

bash
mkdir kolo-group && cd kolo-group

Crie um módulo Go e adicione as quatro bibliotecas da Kolo que o programa usa: a kolo-invite para os convites, a kolo-swarm para encontrar peers e se conectar a eles, a kolo-store para guardar os convites em disco e a kolo-id para a chave de cada membro.

Terminal
go mod init example.com/kolo-group
Terminal
go get github.com/ciranda-dev/kolo-invite@v0.1.0 github.com/ciranda-dev/kolo-swarm@v0.1.0 github.com/ciranda-dev/kolo-store@v0.1.0 github.com/ciranda-dev/kolo-id@v0.1.0

O Go baixa as bibliotecas com o que elas precisam e as adiciona ao go.mod.

3Escreva o programa

Crie um arquivo chamado main.go na pasta kolo-group e cole nele este programa. Cada membro roda o programa com uma pasta própria, -dir, para a sua chave, os seus convites e o topic do grupo. Sem -join, ele cria um grupo novo, ou volta para o grupo em que já está. Com -join, ele pede para entrar com um código de convite.

main.go
// Command group runs one member of a small group: it makes invite codes, answers join requests, or joins with a code.
package main

import (
	"bufio"
	"context"
	"crypto/rand"
	"errors"
	"flag"
	"fmt"
	"io"
	"io/fs"
	"log"
	"net/netip"
	"os"
	"os/signal"
	"path/filepath"
	"slices"
	"strings"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	invite "github.com/ciranda-dev/kolo-invite"
	kolostore "github.com/ciranda-dev/kolo-store"
	koloswarm "github.com/ciranda-dev/kolo-swarm"
)

func main() {
	boot := flag.String("bootstrap", "127.0.0.1:7447", "IP:PORT of the bootstrap node")
	dir := flag.String("dir", "", "folder for this member's key and invites (required)")
	join := flag.String("join", "", "invite code to join a group with")
	name := flag.String("name", "", "name sent with the join request")
	ttl := flag.Duration("ttl", 10*time.Minute, "how long a new invite can be used")
	flag.Parse()
	if *dir == "" {
		log.Fatal("-dir is required")
	}
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()
	log.SetFlags(log.Ltime)
	if err := run(ctx, *boot, *dir, *join, *name, *ttl); err != nil && ctx.Err() == nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context, boot, dir, join, name string, ttl time.Duration) error {
	server, err := netip.ParseAddrPort(boot)
	if err != nil {
		return err
	}
	// An invite code names this key, so it must stay the same across runs.
	id, err := loadIdentity(filepath.Join(dir, "identity.key"))
	if err != nil {
		return err
	}
	db, err := kolostore.OpenPebble(filepath.Join(dir, "invites"))
	if err != nil {
		return err
	}
	defer db.Close()
	in, err := invite.Open(db, id, nil)
	if err != nil {
		return err
	}
	defer in.Close()
	sw, err := koloswarm.New(ctx, "127.0.0.1:0", id, nil)
	if err != nil {
		return err
	}
	defer sw.Close()
	if err := sw.Bootstrap(ctx, []netip.AddrPort{server}); err != nil {
		return err
	}
	log.Printf("me %x", id.PublicKey()[:4])

	groupFile := filepath.Join(dir, "group")
	topic, err := readTopic(groupFile) // zero until this member is in a group
	if err != nil {
		return err
	}
	var code invite.Code
	joining := join != ""
	switch {
	case joining && topic != (koloswarm.Topic{}):
		return errors.New("already in a group")
	case joining:
		if code, err = invite.Parse(join); err != nil {
			return err
		}
		if err := sw.Join(ctx, code.Topic(), &koloswarm.JoinOptions{Lookup: true}); err != nil {
			return err
		}
		log.Printf("looking for the inviter of %s", code)
	default:
		if topic == (koloswarm.Topic{}) {
			rand.Read(topic[:])
			if err := os.WriteFile(groupFile, topic[:], 0o600); err != nil {
				return err
			}
			log.Print("started a new group")
		}
		if err := sw.Join(ctx, topic, nil); err != nil {
			return err
		}
		log.Print("in the group, type invite to make an invite code")
	}
	// Announce takes the swarm's free topics for invites, so it starts after the group topic is joined.
	go in.Announce(ctx, sw)

	peers := feed(ctx, sw.Next)
	invites := feed(ctx, in.Next)
	sc := bufio.NewScanner(os.Stdin)
	lines := feed(ctx, func(context.Context) (string, error) {
		if !sc.Scan() {
			return "", io.EOF
		}
		return strings.TrimSpace(sc.Text()), nil
	})
	answers := make(chan answer, 1)
	var waiting []invite.Event // join requests waiting for y or n, oldest first
	for {
		select {
		case <-ctx.Done():
			return ctx.Err()

		case ev := <-peers:
			switch {
			case ev.Kind == koloswarm.Lost:
				log.Printf("peer %x lost", ev.PublicKey[:4])
			case ev.Kind != koloswarm.Connected:
			case topic != (koloswarm.Topic{}) && slices.Contains(ev.Peer.Topics(), topic):
				log.Printf("member %x connected", ev.Peer.PublicKey()[:4])
			case joining && code.Matches(ev.Peer.PublicKey()):
				log.Printf("asking %x to let us in", ev.Peer.PublicKey()[:4])
				go func() { answers <- ask(ctx, ev.Peer, id, code, name) }()
			default:
				go in.ServePeer(ctx, ev.Peer)
			}

		case a := <-answers:
			if a.err != nil {
				return fmt.Errorf("join: %w", a.err)
			}
			// Leave the invite topic first: the group topic then comes on a new connection.
			sw.Leave(code.Topic())
			topic, joining = a.topic, false
			if err := os.WriteFile(groupFile, topic[:], 0o600); err != nil {
				return err
			}
			if err := sw.Join(ctx, topic, nil); err != nil {
				return err
			}
			log.Print("joined the group, type invite to make an invite code")

		case ev := <-invites:
			switch ev.Kind {
			case invite.Requested:
				waiting = append(waiting, ev)
				log.Printf("%x asks to join as %q: type y to approve or n to deny", ev.Joiner[:4], ev.Data)
			case invite.Withdrawn:
				waiting = slices.DeleteFunc(waiting, func(w invite.Event) bool { return w.Request == ev.Request })
				log.Printf("%x left before an answer", ev.Joiner[:4])
			case invite.Joined:
				log.Printf("%x joined as %q", ev.Joiner[:4], ev.Data)
			case invite.Ended:
				log.Printf("invite %.8s ended: %s", ev.Invite, ev.State)
			}

		case line := <-lines:
			if err := command(in, line, &waiting, topic, ttl); err != nil {
				log.Print(err)
			}
		}
	}
}

// command runs one line typed by the user.
func command(in *invite.Inviter, line string, waiting *[]invite.Event, topic koloswarm.Topic, ttl time.Duration) error {
	switch line {
	case "invite":
		if topic == (koloswarm.Topic{}) {
			return errors.New("join a group first")
		}
		s, info, err := in.Create(&invite.CreateOptions{TTL: ttl, Manual: true})
		if err != nil {
			return err
		}
		log.Printf("invite %.8s, valid until %s, for one person. Send them this code:", info.ID, info.Expires.Format(time.TimeOnly))
		fmt.Println(s)
	case "y", "n":
		if len(*waiting) == 0 {
			return errors.New("no request is waiting")
		}
		req := (*waiting)[0].Request
		*waiting = (*waiting)[1:]
		if line == "n" {
			return in.Deny(req)
		}
		return in.Approve(req, topic[:]) // the joiner gets the group's topic
	case "list":
		infos, err := in.List()
		if err != nil {
			return err
		}
		for _, i := range infos {
			log.Printf("invite %.8s: %s, %d of %d used", i.ID, i.State, i.Used, i.MaxUses)
		}
	case "revoke":
		infos, err := in.List()
		if err != nil {
			return err
		}
		for _, i := range infos {
			if i.State == invite.Active {
				if err := in.Revoke(i.ID); err != nil {
					return err
				}
			}
		}
	default:
		return errors.New("commands: invite, y, n, list, revoke")
	}
	return nil
}

type answer struct {
	topic koloswarm.Topic
	err   error
}

// ask sends a join request on the inviter's connection and returns the group topic the inviter answers with.
func ask(ctx context.Context, p *koloswarm.Peer, id *koloid.Identity, code invite.Code, name string) answer {
	ctx, cancel := context.WithTimeout(ctx, 5*time.Minute) // a person has to answer
	defer cancel()
	payload, err := invite.JoinConn(ctx, p.Conn(), id, code, &invite.JoinOptions{Data: []byte(name), MaxPayload: 32})
	if err != nil {
		return answer{err: err}
	}
	if len(payload) != len(koloswarm.Topic{}) {
		return answer{err: errors.New("the answer is not a group topic")}
	}
	return answer{topic: koloswarm.Topic(payload)}
}

// feed sends what next returns on a channel, until next fails or ctx ends.
func feed[T any](ctx context.Context, next func(context.Context) (T, error)) <-chan T {
	c := make(chan T)
	go func() {
		for {
			v, err := next(ctx)
			if err != nil {
				return
			}
			select {
			case c <- v:
			case <-ctx.Done():
				return
			}
		}
	}()
	return c
}

// readTopic returns the group topic saved at path, or a zero topic if there is none yet.
func readTopic(path string) (koloswarm.Topic, error) {
	b, err := os.ReadFile(path)
	switch {
	case errors.Is(err, fs.ErrNotExist):
		return koloswarm.Topic{}, nil
	case err != nil:
		return koloswarm.Topic{}, err
	case len(b) != len(koloswarm.Topic{}):
		return koloswarm.Topic{}, errors.New("the group file is not a topic")
	}
	return koloswarm.Topic(b), nil
}

// loadIdentity reads the key at path, or makes one and saves it there with mode 0600.
func loadIdentity(path string) (*koloid.Identity, error) {
	id, err := koloid.Load(path)
	if !errors.Is(err, fs.ErrNotExist) {
		return id, err
	}
	if id, err = koloid.Generate(); err != nil {
		return nil, err
	}
	return id, id.SaveNew(path)
}

Como as partes se encaixam:

  • Um swarm e um loop de eventos. feed transforma em canais os eventos do swarm, os eventos de quem convida e as linhas que você digita, então um único select cuida de tudo.
  • Quando um peer se conecta, o loop decide o que ele é. Um peer que compartilha o topic do grupo é um membro. Um peer cuja chave bate com o código em uso é quem convida, e JoinConn pede para entrar, em uma goroutine própria, porque uma pessoa precisa responder. Qualquer outro peer recebe ServePeer, que responde aos pedidos de convite nessa conexão.
  • Announce mantém o swarm nos topics dos convites ativos. Ele começa depois que o swarm entra no topic do grupo, porque ocupa com convites todos os topics livres do swarm.
  • Cada convite precisa de aprovação (Manual), é para uma única pessoa e vale por -ttl, 10 minutos por padrão. Quando a Alice aprova, a carga útil que ela envia é o topic do grupo.
  • A chave é salva na pasta com modo 0600 e não pode mudar, porque um código carrega uma impressão digital da chave de quem convida. Os convites ficam em um store Pebble na mesma pasta, então sobrevivem a uma reinicialização.
  • O que alguém envia com -name vem de outra pessoa, então o programa imprime isso com %q.

4Inicie um nó de bootstrap no Terminal 1

O nó de bootstrap ajuda os peers a se encontrarem. Se o kolo-node ainda não estiver instalado, instale como em Construa um chat no seu terminal. Depois, no Terminal 1, inicie o nó só para o seu computador:

bash
kolo-node run -listen 127.0.0.1:7447 -identity "$(mktemp -d)/node.key" -first

-first inicia uma rede nova: este nó não tem outros nós de entrada para entrar. Ele imprime três linhas e continua rodando. Os seus horários e a sua chave vão ser diferentes:

Texto
time=2026-11-12T04:05:44.555+07:00 level=INFO msg=identity key=15f09167b8cdf405d2bdf6923fe75d5b63b0cd44fd410673afaa7006cda1a64b created=true
time=2026-11-12T04:05:44.555+07:00 level=INFO msg=started version=v0.1.0 addr=127.0.0.1:7447
time=2026-11-12T04:05:44.555+07:00 level=INFO msg=network mode=first entries=0

5Crie o grupo como a Alice no Terminal 2

No Terminal 2, crie uma pasta temporária para a Alice e inicie a Alice:

bash
ALICE="$(mktemp -d)"
go run . -dir "$ALICE"

A Alice cria uma chave e um grupo novo:

Texto
04:05:47 me f8c6cf7f
04:05:47 started a new group
04:05:47 in the group, type invite to make an invite code

6Crie um convite e compartilhe o código

No Terminal 2, digite invite e aperte Enter:

Texto
04:05:48 invite 9c6c8a1b, valid until 04:15:48, for one person. Send them this code:
koloinv03p6txxqnbpccd4ujnmbtiynufzx7lvzzazwugnh3hd4h65yqqblm4xamynhjhejktktg5fdso5yl37avxcmq

O seu código vai ser diferente. Ele carrega uma impressão digital da chave da Alice e um segredo, nunca um endereço. Quem tiver o código pode pedir para entrar, então envie o código só para a pessoa que você convida, por um meio em que você confia, como uma mensagem direta. A aprovação, um único uso e um TTL curto limitam o que um código vazado consegue fazer.

7Entre como o Bob no Terminal 3

No Terminal 3, vá para a mesma pasta kolo-group (use o caminho onde você a criou):

Terminal
cd kolo-group

Depois crie uma pasta para o Bob e rode o programa com o código da Alice (cole o seu):

bash
BOB="$(mktemp -d)"
go run . -dir "$BOB" -name Bob -join koloinv03p6txxqnbpccd4ujnmbtiynufzx7lvzzazwugnh3hd4h65yqqblm4xamynhjhejktktg5fdso5yl37avxcmq

O swarm do Bob busca o topic do convite, encontra a Alice lá e se conecta a ela. O código diz ao Bob qual chave é a da Alice, então ele não envia o seu pedido para mais ninguém:

Texto
04:05:50 me a75d3d88
04:05:50 looking for the inviter of invite 9c6c8a1bef2f16ef57c1a6265543505c
04:05:50 asking f8c6cf7f to let us in

No Terminal 2, a Alice vê o pedido:

Texto
04:05:50 a75d3d88 asks to join as "Bob": type y to approve or n to deny

8Aprove o pedido

No Terminal 2, digite y e aperte Enter. A Alice aceita o Bob, e o convite de uso único se esgota:

Texto
04:05:52 a75d3d88 joined as "Bob"
04:05:52 invite 9c6c8a1b ended: used up
04:05:52 peer a75d3d88 lost
04:05:53 member a75d3d88 connected

No Terminal 3, o Bob recebe o topic do grupo:

Texto
04:05:52 joined the group, type invite to make an invite code
04:05:52 peer f8c6cf7f lost
04:05:53 member f8c6cf7f connected

O Bob saiu do topic do convite, o que fechou aquela primeira conexão (as duas linhas lost), e entrou no topic do grupo, o que trouxe uma conexão nova entre os dois membros. Ele salvou o topic na pasta dele, então da próxima vez roda sem -join. Agora o Bob também pode digitar invite: qualquer membro pode convidar.

9Recuse um pedido

No Terminal 2, digite invite de novo:

Texto
04:05:55 invite 8a07d6f7, valid until 04:15:55, for one person. Send them this code:
koloinv03p6txxqnbpccd4ujnmbtiynufywcsysfs73t527fbg4fmquauvgeth4zi72ed7ugu6u4qxnbdbjpfub3mwha

Em um quarto terminal, vá para a mesma pasta kolo-group (use o caminho onde você a criou):

Terminal
cd kolo-group

Depois crie uma pasta para a Carol e rode o programa com o código novo (cole o seu):

bash
CAROL="$(mktemp -d)"
go run . -dir "$CAROL" -name Carol -join koloinv03p6txxqnbpccd4ujnmbtiynufywcsysfs73t527fbg4fmquauvgeth4zi72ed7ugu6u4qxnbdbjpfub3mwha

Quando o pedido dela aparecer no Terminal 2, digite n:

Texto
04:05:58 dc38e082 asks to join as "Carol": type y to approve or n to deny
04:05:59 peer dc38e082 lost

O programa da Carol imprime a resposta e para:

Texto
04:05:58 me dc38e082
04:05:58 looking for the inviter of invite 8a07d6f700c6f11dfafacc6b7a87bc85
04:05:58 asking f8c6cf7f to let us in
04:05:59 join: invite: denied
exit status 1

Uma recusa fica guardada: a Carol recebe invite: denied toda vez que pergunta de novo com este código. O convite em si continua ativo para outra pessoa.

10Revogue um convite

No Terminal 2, digite invite mais uma vez e depois revoke. Isso revoga todos os convites ativos, aqui aquele com que a Carol foi recusada e o novo:

Texto
04:06:00 invite 0c476029, valid until 04:16:00, for one person. Send them this code:
koloinv03p6txxqnbpccd4ujnmbtiynuf2wrnjlewrba3vgp7b6inmt3ch4rlzmyxlqeemk2ktbefauobihazl3ewpsa
04:06:02 invite 8a07d6f7 ended: revoked
04:06:02 invite 0c476029 ended: revoked

No quarto terminal, rode o programa com uma pasta nova e o código novo (cole o seu), desta vez como o Dave:

bash
DAVE="$(mktemp -d)"
go run . -dir "$DAVE" -name Dave -join koloinv03p6txxqnbpccd4ujnmbtiynuf2wrnjlewrba3vgp7b6inmt3ch4rlzmyxlqeemk2ktbefauobihazl3ewpsa

O programa do Dave imprime a resposta e para:

Texto
04:06:03 me 5d08681f
04:06:03 looking for the inviter of invite 0c476029c0abd75d9a0e58a35478271c
04:06:03 asking f8c6cf7f to let us in
04:06:03 join: invite: revoked
exit status 1

Um convite encerrado continua respondendo assim por 5 minutos (Linger). Depois o segredo dele é apagado e o topic é abandonado, então quem chega tarde não encontra ninguém para perguntar. Digite list para ver todos os convites que a Alice criou:

Texto
04:06:04 invite 9c6c8a1b: used up, 1 of 1 used
04:06:04 invite 8a07d6f7: revoked, 0 of 1 used
04:06:04 invite 0c476029: revoked, 0 of 1 used

Revogar impede novas entradas. Não tira nada do Bob: um membro que foi aceito mantém o topic do grupo.

11Deixe um convite expirar

Pare a Alice com Ctrl-C no Terminal 2 e inicie a Alice de novo com um TTL curto:

bash
go run . -dir "$ALICE" -ttl 20s

Digite list. A chave, o grupo e os convites dela continuam lá, e o Bob se conecta de novo:

Texto
04:06:06 me f8c6cf7f
04:06:06 in the group, type invite to make an invite code
04:06:06 member a75d3d88 connected
04:06:06 invite 9c6c8a1b: used up, 1 of 1 used
04:06:06 invite 8a07d6f7: revoked, 0 of 1 used
04:06:06 invite 0c476029: revoked, 0 of 1 used

Digite invite e espere 20 segundos:

Texto
04:06:07 invite 45d79304, valid until 04:06:27, for one person. Send them this code:
koloinv03p6txxqnbpccd4ujnmbtiynufycnolkk3r4rcks77irkwg432f3h3hm6gbx4yuhg6vpzblq7ftuezdydsk4q
04:06:27 invite 45d79304 ended: expired

No quarto terminal, rode o programa com uma pasta nova e esse código (cole o seu), desta vez como a Erin:

bash
ERIN="$(mktemp -d)"
go run . -dir "$ERIN" -name Erin -join koloinv03p6txxqnbpccd4ujnmbtiynufycnolkk3r4rcks77irkwg432f3h3hm6gbx4yuhg6vpzblq7ftuezdydsk4q

O programa da Erin imprime a resposta e para:

Texto
04:06:29 me 91b38570
04:06:29 looking for the inviter of invite 45d793045f175bcbf070eee6a4912b37
04:06:29 asking f8c6cf7f to let us in
04:06:29 join: invite: expired
exit status 1

A expiração só conta no relógio da Alice. Quem entra não envia nenhum horário, então não existe diferença de relógio entre os dois, e depois que a Alice viu o fim, atrasar o relógio dela não reabre o convite.

12Volte mais tarde

Pare o Bob com Ctrl-C no Terminal 3 e rode o Bob de novo só com a pasta dele:

bash
go run . -dir "$BOB"

Ele volta para o grupo:

Texto
04:06:30 me a75d3d88
04:06:30 in the group, type invite to make an invite code
04:06:30 member f8c6cf7f connected

Para terminar, aperte Ctrl-C no Terminal 3, no Terminal 2 e por último no Terminal 1.

O que acabou de acontecer

  • O código carregava uma impressão digital da chave da Alice e um segredo de 256 bits. O Bob encontrou a Alice em um topic derivado do segredo, conferiu a chave dela com a impressão digital e enviou um pedido criptografado para uma chave derivada do segredo e assinado com a própria chave.
  • A Alice decidiu sozinha, com o próprio relógio e o próprio store. Um uso é contado em disco antes de a resposta sair, então um convite de uso único nunca deixa duas pessoas entrarem.
  • O nó de bootstrap e a DHT viram o topic do convite, nunca o código. Eles podiam ver que o endereço do Bob buscou um topic anunciado pela chave da Alice. Veja Topics.
  • O topic do grupo serve para os membros se encontrarem, não é um segredo: os servidores da DHT também o veem. Uma aplicação real envia na carga útil o que dá acesso, por exemplo um ID de log e uma capability, e confere a chave de cada membro. Joiners lista as chaves que um convite aceitou, com o que cada uma enviou.

Antes de construir em cima disso

  • O swarm de quem entra busca o topic do convite quando começa, e depois a cada 10 minutos (LookupInterval da kolo-swarm) mais até um quinto desse tempo, ao acaso. Quem começa antes de quem convida estar online pode esperar até uns 12 minutos.
  • Um swarm entra em 16 topics ao mesmo tempo por padrão (MaxTopics), os do grupo e os dos convites juntos. Os convites que passam disso esperam um topic livre, então dê um TTL aos convites e revogue os que você não precisa mais.
  • ServePeer precisa ser o único a aceitar streams na sua conexão. Este programa não roda mais nada com os membros. Uma aplicação que roda outro protocolo com eles decide, por conexão, qual deles a atende, por exemplo pelo topic, como aqui.
  • JoinConn também funciona em uma conexão que quem entra já tem com quem convida, o que dispensa a busca na DHT.
  • A página da kolo-invite lista cada limite, as notas de segurança e os erros.

O que não foi testado

Todas as execuções deste guia foram em um único computador, em 127.0.0.1. Um NAT real e os comandos do Windows não foram testados.

Próximos passos