spotlib

spotlib

Spot connection library for Go. Enables secure, end-to-end encrypted communication between clients through the Spot network.

Features

• End-to-end encrypted messaging using cryptographic identity cards
• Automatic connection management with reconnection support
• Request-response and fire-and-forget messaging patterns
• net.PacketConn interface for UDP-like communication
• Event-based status notifications
• ID card caching with automatic updates

Installation

go get github.com/KarpelesLab/spotlib

Quick Start

Creating a Client

package main

import (
    "context"
    "log"
    "time"

    "github.com/KarpelesLab/spotlib"
)

func main() {
    // Create a new client with an ephemeral key
    client, err := spotlib.New()
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Wait for the client to come online
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    if err := client.WaitOnline(ctx); err != nil {
        log.Fatal("failed to connect:", err)
    }

    log.Println("Connected! Client ID:", client.TargetId())
}

Using a Persistent Identity

The easiest way to maintain the same identity across restarts is to use NewDiskStore:

// Create a disk store that persists keys to ~/.config/spot/ (or equivalent)
store, err := spotlib.NewDiskStore()
if err != nil {
    log.Fatal(err)
}

// Create client with the stored keychain
client, err := spotlib.New(store.Keychain())

The disk store automatically:

• Creates the storage directory if it doesn't exist
• Generates a new ECDSA P-256 key if no keys exist
• Loads existing keys on subsequent runs
• Stores keys in PEM-encoded PKCS#8 format as id_<type>.key files

You can also specify a custom path:

store, err := spotlib.NewDiskStoreWithPath("/path/to/keys")

Alternatively, manage keys manually:

import (
    "crypto/ecdsa"
    "crypto/elliptic"
    "crypto/rand"

    "github.com/KarpelesLab/spotlib"
)

// Generate or load your private key
privateKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

// Create client with the key
client, err := spotlib.New(privateKey)

You can also pass a *cryptutil.Keychain for more advanced key management.

Sending Messages

Query (Request-Response)

// Send an encrypted query and wait for response
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

response, err := client.Query(ctx, "k.recipientID/endpoint", []byte("hello"))
if err != nil {
    log.Fatal(err)
}
log.Println("Response:", string(response))

Send (Fire-and-Forget)

// Send a one-way encrypted message
err := client.SendTo(ctx, "k.recipientID/endpoint", []byte("hello"))

Receiving Messages

Register handlers for incoming messages on specific endpoints:

import "github.com/KarpelesLab/spotproto"

client.SetHandler("myendpoint", func(msg *spotproto.Message) ([]byte, error) {
    log.Printf("Received from %s: %s", msg.Sender, string(msg.Body))

    // Return a response (or nil for no response)
    return []byte("acknowledged"), nil
})

Monitoring Connection Status

// Listen for status changes
go func() {
    for ev := range client.Events.On("status") {
        status := emitter.Arg[int](ev, 0)
        if status == 1 {
            log.Println("Online!")
        } else {
            log.Println("Offline")
        }
    }
}()

// Or wait for online status
client.Events.On("online") // triggered when going online

PacketConn Interface

For UDP-like communication patterns, use the net.PacketConn interface:

conn, err := client.ListenPacket("udp-endpoint")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

// Send data
addr := spotlib.SpotAddr("k.recipientID/udp-endpoint")
conn.WriteTo([]byte("hello"), addr)

// Receive data
buf := make([]byte, 4096)
n, remoteAddr, err := conn.ReadFrom(buf)
if err != nil {
    log.Fatal(err)
}
log.Printf("Received %d bytes from %s", n, remoteAddr)

Blob Storage

Store and retrieve encrypted data that persists across sessions:

// Store data (encrypted, only readable by this client)
err := client.StoreBlob(ctx, "my-key", []byte("secret data"))

// Retrieve data
data, err := client.FetchBlob(ctx, "my-key")

// Delete data
err := client.StoreBlob(ctx, "my-key", nil)

Note: Blob storage is best-effort and has a size limit of ~49KB. Data may be purged after extended periods without access.

Group Membership

// Get members of a group
members, err := client.GetGroupMembers(ctx, groupKey)
for _, member := range members {
    log.Println("Member:", member)
}

Server Time

serverTime, err := client.GetTime(ctx)
log.Println("Server time:", serverTime)

Addressing

Spot uses the following address formats:

Messages to k. addresses are automatically encrypted and signed. The recipient's public key is fetched and cached automatically.

Client Options

The New() function accepts various optional parameters:

client, err := spotlib.New(
    privateKey,                        // crypto.Signer for identity
    keychain,                          // *cryptutil.Keychain
    eventHub,                          // *emitter.Hub for custom event handling
    map[string]spotlib.MessageHandler{ // Initial handlers
        "endpoint": myHandler,
    },
    map[string]string{                 // Metadata for ID card
        "name": "my-client",
    },
)

Default Handlers

The client registers these handlers automatically:

API Reference

Client Methods

Storage

License

See LICENSE file for details.