hello

README

Hello-Message Go SDK

A Go SDK for AI agents to securely generate and verify "hello" authentication messages using Ethereum-based cryptographic signatures.

Part of the Hello-Message protocol.

Installation

go get github.com/aimxlabs/hello-message-go

Usage

Generate a Hello Message

package main

import (
	"fmt"
	"os"

	hello "github.com/aimxlabs/hello-message-go"
)

func main() {
	h, err := hello.New(func() string {
		return os.Getenv("PRIVATE_KEY")
	})
	if err != nil {
		panic(err)
	}

	fmt.Println("Address:", h.GetAddress())

	msg, err := h.GenerateHelloMessage()
	if err != nil {
		panic(err)
	}

	fmt.Println("Hello Message:", msg)
}

Verify a Hello Message

result := hello.VerifySignature(helloMessage)
if result.Valid {
	fmt.Println("Valid message from:", result.Address)
} else {
	fmt.Println("Invalid message:", result.Error)
}

API

New(keyProvider func() string) (*Hello, error)

Creates a new Hello instance. The keyProvider is a function that returns a hex-encoded Ethereum private key.

(*Hello) GetAddress() string

Returns the Ethereum address derived from the private key.

(*Hello) GenerateHelloMessage() (string, error)

Generates a signed hello message with a default 5-second expiration. Returns a base64-encoded JSON string.

(*Hello) GenerateHelloMessageWithExpiry(expiresInSeconds int) (string, error)

Generates a signed hello message with a custom expiration.

VerifySignature(helloMessage string) VerifyResult

Verifies a base64-encoded hello message. Returns a VerifyResult with:

• Valid - whether the signature is valid and not expired
• Address - the claimed signer address
• Nonce - the UUID nonce
• Expires - the expiration timestamp

License

MIT

Documentation

Index

• type Hello
  • func New(keyProvider func() string) (*Hello, error)
  • func (h *Hello) GenerateHelloMessage() (string, error)
  • func (h *Hello) GenerateHelloMessageWithExpiry(expiresInSeconds int) (string, error)
  • func (h *Hello) GetAddress() string
• type HelloMessage
• type VerifyResult
  • func VerifySignature(helloMessage string) VerifyResult

Types

type Hello

type Hello struct {
	// contains filtered or unexported fields
}

Hello provides methods for generating and verifying hello authentication messages.

func New

func New(keyProvider func() string) (*Hello, error)

New creates a new Hello instance with the given key provider. The key provider is a function that returns a hex-encoded Ethereum private key.

func (*Hello) GenerateHelloMessage

func (h *Hello) GenerateHelloMessage() (string, error)

GenerateHelloMessage generates a signed hello message with the default 5-second expiration.

func (*Hello) GenerateHelloMessageWithExpiry

func (h *Hello) GenerateHelloMessageWithExpiry(expiresInSeconds int) (string, error)

GenerateHelloMessageWithExpiry generates a signed hello message with a custom expiration in seconds.

func (*Hello) GetAddress

func (h *Hello) GetAddress() string

GetAddress returns the Ethereum address corresponding to the private key.

type HelloMessage

type HelloMessage struct {
	Message   string `json:"message"`
	Signature string `json:"signature"`
	Address   string `json:"address"`
}

HelloMessage is the structure of a hello authentication message.

type VerifyResult

type VerifyResult struct {
	Valid   bool   `json:"valid"`
	Address string `json:"address"`
	Nonce   string `json:"nonce"`
	Expires string `json:"expires"`
	Error   string `json:"error,omitempty"`
}

VerifyResult contains the result of verifying a hello message.

func VerifySignature

func VerifySignature(helloMessage string) VerifyResult

VerifySignature verifies a base64-encoded hello message and returns the result.