kolo docsbeta

Invita a alguien a un grupo, en un programa de terminal

Una guía paso a paso. Un miembro crea un código de invitación, alguien se une con él, y el miembro aprueba, rechaza o revoca.

En esta página

Un grupo necesita una forma de dejar entrar a alguien nuevo. Con kolo-invite, un miembro crea un código de invitación y se lo envía a esa persona, en un chat o en un mensaje. La persona ejecuta la aplicación con el código, el miembro ve la petición y responde que sí o que no, y el nuevo miembro recibe lo que necesita para encontrar el grupo.

En esta guía escribes un programa pequeño y lo ejecutas dos veces: como Alice, que crea un grupo, y como Bob, que se une a él. Después pruebas un rechazo, una revocación y una caducidad. Todo se queda en tu ordenador, en la dirección 127.0.0.1, con un nodo de bootstrap en un tercer terminal.

1Comprueba lo que necesitas

Necesitas Go 1.26 o posterior y cuatro ventanas de terminal. Construye un chat en tu terminal explica cómo instalar Go. Abre las cuatro ventanas y ponlas una al lado de otra:

Abre la app Terminal y pulsa Cmd+N tres veces para tener tres ventanas más.

Aquí el Terminal 1 ejecuta el nodo de bootstrap, el Terminal 2 ejecuta a Alice, el Terminal 3 ejecuta a Bob y el cuarto terminal ejecuta a las personas que intentan unirse después.

2Crea un módulo y descarga las bibliotecas

En el Terminal 2, crea una carpeta para el programa y entra en ella:

bash
mkdir kolo-group && cd kolo-group

Crea un módulo de Go y añade las cuatro bibliotecas de Kolo que usa el programa: kolo-invite para las invitaciones, kolo-swarm para encontrar peers y conectarse a ellos, kolo-store para guardar las invitaciones en disco y kolo-id para la clave de cada miembro.

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

Go las descarga junto con lo que necesitan y las añade a go.mod.

3Escribe el programa

Crea un archivo llamado main.go en la carpeta kolo-group y pega en él este programa. Cada miembro lo ejecuta con una carpeta propia, -dir, para su clave, sus invitaciones y el topic del grupo. Sin -join crea un grupo nuevo, o vuelve al grupo en el que ya está. Con -join pide unirse con un código de invitación.

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)
}

Cómo encaja todo:

  • Un swarm y un bucle de eventos. feed convierte en canales los eventos del swarm, los eventos de quien invita y las líneas que escribes, así que un solo select los atiende todos.
  • Cuando un peer se conecta, el bucle decide qué es. Un peer que comparte el topic del grupo es un miembro. Un peer cuya clave coincide con el código en uso es quien invita, y JoinConn le pide entrar, en su propia goroutine, porque una persona tiene que responder. Cualquier otro peer recibe ServePeer, que responde a las peticiones de invitación en esa conexión.
  • Announce mantiene el swarm unido a los topics de las invitaciones vivas. Arranca después de unirse al topic del grupo, porque toma para las invitaciones todos los topics libres del swarm.
  • Cada invitación necesita aprobación (Manual), es para una sola persona y vale durante -ttl, 10 minutos por defecto. Cuando Alice aprueba, la carga útil que envía es el topic del grupo.
  • La clave se guarda en la carpeta con modo 0600 y no debe cambiar, porque un código lleva una huella de la clave de quien invita. Las invitaciones viven en un almacén Pebble en la misma carpeta, así que sobreviven a un reinicio.
  • Lo que alguien envía con -name viene de otra persona, así que el programa lo imprime con %q.

4Arranca un nodo de bootstrap en el Terminal 1

El nodo de bootstrap ayuda a los peers a encontrarse. Si aún no tienes kolo-node instalado, instálalo como en Construye un chat en tu terminal. Después, en el Terminal 1, arráncalo solo para tu ordenador:

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

-first arranca una red nueva: este nodo no tiene otros nodos de entrada a los que unirse. Imprime tres líneas y sigue en marcha. Tus horas y tu clave serán distintas:

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

5Crea el grupo como Alice en el Terminal 2

En el Terminal 2, crea una carpeta temporal para Alice y arráncala:

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

Alice crea una clave y un grupo nuevo:

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

6Crea una invitación y comparte el código

En el Terminal 2, escribe invite y pulsa Intro:

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

Tu código será distinto. Lleva una huella de la clave de Alice y un secreto, nunca una dirección. Quien tenga el código puede pedir unirse, así que envíalo solo a la persona que invitas, por un medio en el que confíes, como un mensaje directo. La aprobación, un solo uso y un TTL corto limitan lo que puede hacer un código filtrado.

7Únete como Bob en el Terminal 3

En el Terminal 3, ve a la misma carpeta kolo-group (usa la ruta donde la creaste):

Terminal
cd kolo-group

Después crea una carpeta para Bob y ejecuta el programa con el código de Alice (pega el tuyo):

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

El swarm de Bob busca el topic de la invitación, encuentra allí a Alice y se conecta con ella. El código le dice a Bob qué clave es la de Alice, así que no envía su petición a nadie más:

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

En el Terminal 2, Alice ve la petición:

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

8Aprueba la petición

En el Terminal 2, escribe y y pulsa Intro. Alice acepta a Bob, y la invitación de un solo uso queda agotada:

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

En el Terminal 3, Bob recibe el topic del 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

Bob abandonó el topic de la invitación, lo que cerró esa primera conexión (las dos líneas lost), y se unió al topic del grupo, lo que trajo una conexión nueva entre los dos miembros. Guardó el topic en su carpeta, así que la próxima vez se ejecuta sin -join. Ahora Bob también puede escribir invite: cualquier miembro puede invitar.

9Rechaza una petición

En el Terminal 2, escribe invite otra vez:

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

En un cuarto terminal, ve a la misma carpeta kolo-group (usa la ruta donde la creaste):

Terminal
cd kolo-group

Después crea una carpeta para Carol y ejecuta el programa con el código nuevo (pega el tuyo):

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

Cuando su petición aparezca en el Terminal 2, escribe 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

El programa de Carol imprime la respuesta y se detiene:

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

Un rechazo queda guardado: Carol recibe invite: denied cada vez que vuelve a preguntar con este código. La invitación sigue activa para otra persona.

10Revoca una invitación

En el Terminal 2, escribe invite una vez más y después revoke. Revoca todas las invitaciones activas, aquí la que se le rechazó a Carol y la nueva:

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

En el cuarto terminal, ejecuta el programa con una carpeta nueva y el código nuevo (pega el tuyo), esta vez como Dave:

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

El programa de Dave imprime la respuesta y se detiene:

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

Una invitación terminada sigue respondiendo así durante 5 minutos (Linger). Después se borra su secreto y se abandona su topic, así que quien llegue tarde no encuentra a nadie a quien preguntar. Escribe list para ver todas las invitaciones que creó Alice:

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

Revocar detiene las uniones nuevas. No le quita nada a Bob: un miembro que fue aceptado conserva el topic del grupo.

11Deja que una invitación caduque

Para a Alice con Ctrl-C en el Terminal 2 y arráncala otra vez con un TTL corto:

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

Escribe list. Su clave, su grupo y sus invitaciones siguen ahí, y Bob vuelve a conectarse:

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

Escribe invite y espera 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

En el cuarto terminal, ejecuta el programa con una carpeta nueva y ese código (pega el tuyo), esta vez como Erin:

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

El programa de Erin imprime la respuesta y se detiene:

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

La caducidad solo cuenta en el reloj de Alice. Quien se une no envía ninguna hora, así que no hay desfase entre los dos, y cuando Alice ya ha visto el final, retrasar su reloj no reabre la invitación.

12Vuelve más tarde

Para a Bob con Ctrl-C en el Terminal 3 y ejecútalo otra vez solo con su carpeta:

bash
go run . -dir "$BOB"

Vuelve al 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, pulsa Ctrl-C en el Terminal 3, en el Terminal 2 y por último en el Terminal 1.

Qué acaba de pasar

  • El código llevaba una huella de la clave de Alice y un secreto de 256 bits. Bob encontró a Alice en un topic derivado del secreto, comprobó su clave con la huella y envió una petición cifrada para una clave derivada del secreto y firmada con su propia clave.
  • Alice decidió en solitario, con su propio reloj y su propio almacén. Un uso se cuenta en disco antes de que salga la respuesta, así que una invitación de un solo uso nunca deja entrar a dos personas.
  • El nodo de bootstrap y la DHT vieron el topic de la invitación, nunca el código. Podían ver que la dirección de Bob buscaba un topic que anunciaba la clave de Alice. Consulta Topics.
  • El topic del grupo sirve para que los miembros se encuentren, no es un secreto: los servidores de la DHT también lo ven. Una aplicación real envía en la carga útil lo que da acceso, por ejemplo un ID de log y una capacidad, y comprueba la clave de cada miembro. Joiners lista las claves que aceptó una invitación, con lo que envió cada una.

Antes de construir sobre esto

  • El swarm de quien se une busca el topic de la invitación al arrancar, y después cada 10 minutos (LookupInterval de kolo-swarm) más hasta una quinta parte de ese tiempo al azar. Quien arranca antes de que quien invita esté en línea puede esperar hasta unos 12 minutos.
  • Un swarm se une a 16 topics a la vez por defecto (MaxTopics), los del grupo y los de las invitaciones juntos. Las invitaciones que pasan de ahí esperan un topic libre, así que dales un TTL y revoca las que ya no necesites.
  • ServePeer tiene que ser lo único que acepta streams en su conexión. Este programa no ejecuta nada más con los miembros. Una aplicación que ejecuta otro protocolo con ellos decide en cada conexión cuál la atiende, por ejemplo según el topic, como aquí.
  • JoinConn también funciona en una conexión que quien se une ya tiene con quien invita, y así se ahorra la búsqueda en la DHT.
  • La página de kolo-invite recoge cada límite, las notas de seguridad y los errores.

Qué no se ha probado

Todas las ejecuciones de esta guía se hicieron en un solo ordenador, en 127.0.0.1. No se han probado un NAT real ni los comandos de Windows.

Siguientes pasos