hyperspace

Hyperspace

Hyperspace is a Go library that provides P2P connectivity using the Holepunch ecosystem's Hyperbeam. It enables two parties with X25519 keypairs to establish direct connections through NAT traversal.

Overview

Hyperspace derives a passcode from X25519 keys and uses it with Hyperbeam for P2P connections. Both parties compute the same passcode from their X25519 shared secret, enabling them to find each other via the DHT and establish an encrypted connection.

Alice                              Bob
  │                                  │
  │ X25519(keyA_secret, keyB_public)│ X25519(keyB_secret, keyA_public)
  │         = shared_secret          │         = shared_secret
  │                                  │
  │ SHA-256(shared_secret ||         │ SHA-256(shared_secret ||
  │          "hyperspace-v1")         │          "hyperspace-v1")
  │         = passcode               │         = passcode
  │                                  │
  │     z-base-32(passcode)          │     z-base-32(passcode)
  │                                  │
  │       hyperbeam <passcode>       │       hyperbeam <passcode>
  │                                  │
  └──────────── DHT ─────────────────┘
                    │
              P2P Connection

Installation

go get codeberg.org/OperatorFoundation/hyperspace

Prerequisites

Hyperbeam must be installed:

npm install -g hyperbeam

Or use the library's installation function:

if err := hyperspace.InstallHyperbeam(); err != nil {
    log.Fatal(err)
}

Quick Start

package main

import (
    "fmt"
    "log"

    "codeberg.org/OperatorFoundation/hyperspace"
)

func main() {
    // Your X25519 private key (32 bytes)
    myPrivateKey := make([]byte, 32)
    // ... load from secure storage ...

    // Peer's X25519 public key (32 bytes)
    theirPublicKey := make([]byte, 32)
    // ... received from peer ...

    // Derive passcode
    passcode, err := hyperspace.DerivePasscodeFromKeys(myPrivateKey, theirPublicKey)
    if err != nil {
        log.Fatal(err)
    }

    // Convert to z-base-32 (format expected by Hyperbeam)
    z32 := hyperspace.PasscodeToZ32(passcode)
    fmt.Printf("Passcode: %s\n", z32)

    // Connect via Hyperbeam
    conn, err := hyperspace.Connect(z32)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // Use the connection (implements io.ReadWriteCloser)
    conn.Write([]byte("Hello, peer!"))

    buf := make([]byte, 1024)
    n, err := conn.Read(buf)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Received: %s\n", buf[:n])
}

API Reference

Passcode Derivation

func ComputeSharedSecret(privateKey, peerPublicKey []byte) ([]byte, error)

Performs X25519 key exchange between a private key and a peer's public key.

sharedSecret, err := hyperspace.ComputeSharedSecret(myPrivateKey, theirPublicKey)

• privateKey: Your X25519 private key (32 bytes)
• peerPublicKey: Peer's X25519 public key (32 bytes)
• Returns: The shared secret (32 bytes)

func DerivePasscode(sharedSecret []byte) ([]byte, error)

Derives a 32-byte passcode from an X25519 shared secret using SHA-256.

passcode, err := hyperspace.DerivePasscode(sharedSecret)

• sharedSecret: The X25519 shared secret (32 bytes)
• Returns: The derived passcode (32 bytes)

The passcode is computed as: SHA-256(sharedSecret || "hyperspace-v1")

func DerivePasscodeFromKeys(myPrivateKey, theirPublicKey []byte) ([]byte, error)

Convenience function that combines ComputeSharedSecret and DerivePasscode.

passcode, err := hyperspace.DerivePasscodeFromKeys(myPrivateKey, theirPublicKey)

Encoding Functions

func PasscodeToZ32(passcode []byte) string

Encodes a passcode to z-base-32 format. This is the format expected by Hyperbeam.

z32 := hyperspace.PasscodeToZ32(passcode)
// Example: "ybxwmkpqnbfdtpjyquvfrk3q5zgjmqse9r4k6hyno81gdmwz4sco"

func Z32ToPasscode(z32 string) ([]byte, error)

Decodes a z-base-32 string back to a passcode.

passcode, err := hyperspace.Z32ToPasscode(z32)

func PasscodeToHex(passcode []byte) string

Converts a passcode to hexadecimal format (useful for debugging).

hex := hyperspace.PasscodeToHex(passcode)
// Example: "a1b2c3d4..."

Hyperbeam Management

func IsHyperbeamInstalled() bool

Returns true if the hyperbeam executable is available.

if hyperspace.IsHyperbeamInstalled() {
    // hyperbeam is available
}

func InstallHyperbeam() error

Installs hyperbeam globally via npm. Returns an error if npm is not available or installation fails.

if err := hyperspace.InstallHyperbeam(); err != nil {
    log.Fatal(err)
}

func EnsureHyperbeam() error

Ensures hyperbeam is installed, installing if necessary.

if err := hyperspace.EnsureHyperbeam(); err != nil {
    log.Fatal(err)
}

func HyperbeamPath() (string, error)

Returns the path to the hyperbeam executable.

path, err := hyperspace.HyperbeamPath()

Connection

func Connect(passcode string) (*Connection, error)

Establishes a P2P connection via Hyperbeam using the given passcode (z-base-32 format).

conn, err := hyperspace.Connect("ybxwmkpqnbfdtpjyquvfrk3q5zgjmqse9r4k6hyno81gdmwz4sco")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

func ConnectWithKeys(myPrivateKey, theirPublicKey []byte) (*Connection, error)

Convenience function that derives the passcode from keys and connects.

conn, err := hyperspace.ConnectWithKeys(myPrivateKey, theirPublicKey)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

type Connection

Represents an active Hyperbeam connection. Implements io.ReadWriteCloser.

type Connection struct {
    // Has unexported fields.
}

func (c *Connection) Read(p []byte) (n int, err error)
func (c *Connection) Write(p []byte) (n int, err error)
func (c *Connection) Close() error
func (c *Connection) Stderr() io.Reader

Integration with Velada

Hyperspace is designed to integrate with Velada, which provides Nahoft-compatible key management via the keychain library.

Basic Integration

import (
    "codeberg.org/OperatorFoundation/hyperspace"
    "codeberg.org/OperatorFoundation/keychain"
)

func ConnectToContact(store *keychain.Store, contactID string) (*hyperspace.Connection, error) {
    // Get the default identity's private key
    identity, err := store.GetDefaultIdentity()
    if err != nil {
        return nil, fmt.Errorf("get identity: %w", err)
    }

    // Load the private key (protected memory)
    privBuf, _, err := store.LoadSecret(identity.X25519KeyID)
    if err != nil {
        return nil, fmt.Errorf("load private key: %w", err)
    }
    defer privBuf.Destroy()

    // Get the contact's public key
    addressBook := keychain.NewAddressBook(store)
    pubKeys, err := addressBook.GetContactPublicKeys(contactID)
    if err != nil {
        return nil, fmt.Errorf("get contact public key: %w", err)
    }

    // Derive passcode
    passcode, err := hyperspace.DerivePasscodeFromKeys(privBuf.Bytes(), pubKeys.X25519PublicKey)
    if err != nil {
        return nil, fmt.Errorf("derive passcode: %w", err)
    }

    // Connect
    return hyperspace.Connect(hyperspace.PasscodeToZ32(passcode))
}

With CryptoManager (Velada's wrapper)

import (
    "codeberg.org/OperatorFoundation/hyperspace"
    "codeberg.org/OperatorFoundation/velada"
)

// Velada's CryptoManager provides higher-level access
func ConnectWithCryptoManager(cm *velada.CryptoManager, contactID string) (*hyperspace.Connection, error) {
    // Get your public key
    myPublicKey, err := cm.GetPublicKey()
    if err != nil {
        return nil, err
    }

    // Get contact's public key
    theirPublicKey, err := cm.GetContactPublicKey(contactID)
    if err != nil {
        return nil, err
    }

    // Note: You'll need access to the private key from the keychain.
    // This may require extending Velada's CryptoManager to expose
    // a method for passcode derivation, or exposing the underlying Store.

    // ... derive passcode and connect ...
}

Recommended Integration Pattern

For Velada, consider adding a helper function:

// In velada/crypto.go (proposed addition)
func (cm *CryptoManager) DeriveHyperspacePasscode(contactID string) ([]byte, error) {
    // Get identity's X25519 key ID
    identity, err := cm.store.GetDefaultIdentity()
    if err != nil {
        return nil, err
    }

    // Load private key
    privBuf, _, err := cm.store.LoadSecret(identity.X25519KeyID)
    if err != nil {
        return nil, err
    }
    defer privBuf.Destroy()

    // Get contact's public key
    pubKeys, err := cm.addressBook.GetContactPublicKeys(contactID)
    if err != nil {
        return nil, err
    }

    // Derive passcode
    return hyperspace.DerivePasscodeFromKeys(privBuf.Bytes(), pubKeys.X25519PublicKey)
}

Security Properties

How It Works

1. X25519 Key Exchange: Both parties have X25519 keypairs. Each computes the shared secret using their private key and the peer's public key.

2. Passcode Derivation: The shared secret is hashed with a context string:

   passcode = SHA-256(sharedSecret || "hyperspace-v1")
   

3. z-base-32 Encoding: The passcode is encoded in z-base-32, a human-friendly encoding used by the Holepunch ecosystem.

4. Hyperbeam Connection: The passcode is passed to hyperbeam, which uses it to derive a keypair for DHT announcement and encrypted connection establishment.

5. NAT Traversal: Hyperbeam uses the DHT for peer discovery and UDP hole-punching for NAT traversal.

Constants

const (
    // PasscodeContext is the domain separation string
    PasscodeContext = "hyperspace-v1"

    // PasscodeSize is the size of the derived passcode in bytes
    PasscodeSize = 32
)

Errors

var (
    // ErrInvalidKeySize is returned when a key is not 32 bytes
    ErrInvalidKeySize = fmt.Errorf("key must be %d bytes", 32)

    // ErrHyperbeamNotFound is returned when hyperbeam is not installed
    ErrHyperbeamNotFound = fmt.Errorf("hyperbeam not found - install with: npm install -g hyperbeam")
)

License

MIT