Skip to content

API Reference

Internal API documentation for Orb developers.

Package Structure

orb/
├── cmd/                # CLI commands
├── internal/           # Internal packages
│   ├── crypto/        # Cryptography
│   ├── filesystem/    # File operations
│   ├── relay/         # Relay server
│   ├── session/       # Session management
│   ├── tui/           # Terminal UI
│   └── tunnel/        # Encrypted tunnel
├── pkg/               # Public packages
│   └── protocol/      # Wire protocol
└── main.go            # Entry point

Key Packages

crypto

Purpose: Cryptographic primitives

Types:

type AEAD struct {
    cipher    cipher.AEAD
    sendNonce uint64
    recvNonce uint64
}

func NewAEAD(key []byte) (*AEAD, error)
func (a *AEAD) Encrypt(plaintext []byte) ([]byte, error)
func (a *AEAD) Decrypt(ciphertext []byte) ([]byte, error)

Functions:

func DeriveKey(passcode, sessionID []byte) []byte
func GenerateKeyPair() (private, public []byte, err error)

Noise Protocol

Orb uses the Noise Protocol Framework for secure key exchange and handshake. The implementation follows the Noise_XX pattern:

  • X: Static key transmitted
  • X: Static key transmitted (both parties)

This ensures mutual authentication and forward secrecy.

filesystem

Purpose: Secure file operations

Functions:

func SanitizePath(base, requested string) (string, error)
func ReadFile(base, path string) ([]byte, error)
func ListDirectory(base, path string) ([]FileInfo, error)

tunnel

Purpose: Encrypted communication channel

Types:

type Tunnel struct {
    conn   *websocket.Conn
    aead   *crypto.AEAD
}

func NewTunnel(conn *websocket.Conn, key []byte) *Tunnel
func (t *Tunnel) Send(frame *protocol.Frame) error
func (t *Tunnel) Receive() (*protocol.Frame, error)

protocol

Purpose: Wire protocol definitions

Types:

type FrameType uint8

const (
    FrameTypeRequest FrameType = iota
    FrameTypeResponse
    FrameTypeError
)

type Frame struct {
    Type      FrameType
    Operation string
    Path      string
    Data      []byte
}

CLI Commands

share

func shareCmd() *cobra.Command {
    // Implementation in cmd/share.go
}

connect

func connectCmd() *cobra.Command {
    // Implementation in cmd/connect.go
}

relay

func relayCmd() *cobra.Command {
    // Implementation in cmd/relay.go
}

Configuration

Currently no configuration files. All options via flags.

Error Handling

Use standard Go error handling:

if err != nil {
    return fmt.Errorf("operation failed: %w", err)
}

Testing

go test ./...

Next Steps