handshake

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 5, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package handshake implements ZK-enhanced peer authentication and session management.

Index

Constants

View Source 
const (
	// ProtocolID is the legacy protocol identifier (unsigned challenges).
	ProtocolID = "/lango/handshake/1.0.0"

	// ProtocolIDv11 is the signed-challenge protocol (v1.1).
	ProtocolIDv11 = "/lango/handshake/1.1.0"
)

Protocol version constants for handshake negotiation.

View Source 
const NonceSize = 32

NonceSize is the expected byte length of a nonce.

Variables

This section is empty.

Functions

This section is empty.

Types

type ApprovalFunc 

type ApprovalFunc func(ctx context.Context, pending *PendingHandshake) (bool, error)

ApprovalFunc is called to request user approval for an incoming handshake. Uses the callback pattern to avoid import cycles with the approval package.

type Challenge 

type Challenge struct {
	Nonce     []byte `json:"nonce"`
	Timestamp int64  `json:"timestamp"`
	SenderDID string `json:"senderDid"`
	PublicKey []byte `json:"publicKey,omitempty"` // v1.1: initiator's public key
	Signature []byte `json:"signature,omitempty"` // v1.1: ECDSA signature over canonical payload
}

Challenge is sent by the initiator to start the handshake.

type ChallengeResponse 

type ChallengeResponse struct {
	Nonce     []byte `json:"nonce"`
	Signature []byte `json:"signature,omitempty"`
	ZKProof   []byte `json:"zkProof,omitempty"`
	DID       string `json:"did"`
	PublicKey []byte `json:"publicKey"`
}

ChallengeResponse is the target's reply with proof of identity.

type Config 

type Config struct {
	Wallet                 wallet.WalletProvider
	Sessions               *SessionStore
	ApprovalFn             ApprovalFunc
	ZKProver               ZKProverFunc
	ZKVerifier             ZKVerifierFunc
	ZKEnabled              bool
	Timeout                time.Duration
	AutoApproveKnown       bool
	NonceCache             *NonceCache
	RequireSignedChallenge bool
	Logger                 *zap.SugaredLogger
}

Config configures the Handshaker.

type Handshaker 

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

Handshaker manages peer authentication using wallet signatures or ZK proofs.

func NewHandshaker 

func NewHandshaker(cfg Config) *Handshaker

NewHandshaker creates a new peer authenticator.

func (*Handshaker) HandleIncoming 

func (h *Handshaker) HandleIncoming(ctx context.Context, s network.Stream) (*Session, error)

HandleIncoming processes an incoming handshake request.

func (*Handshaker) Initiate 

func (h *Handshaker) Initiate(ctx context.Context, s network.Stream, localDID string) (*Session, error)

Initiate starts a handshake with a remote peer over the given stream.

func (*Handshaker) StreamHandler 

func (h *Handshaker) StreamHandler() network.StreamHandler

StreamHandler returns a libp2p stream handler for incoming handshakes.

func (*Handshaker) StreamHandlerV11 

func (h *Handshaker) StreamHandlerV11() network.StreamHandler

StreamHandlerV11 returns a libp2p stream handler for v1.1 (signed challenge) handshakes. Uses the same HandleIncoming logic since it handles both signed and unsigned challenges.

type InvalidationReason 

type InvalidationReason string

InvalidationReason describes why a session was invalidated. 

const (
	ReasonLogout           InvalidationReason = "logout"
	ReasonReputationDrop   InvalidationReason = "reputation_drop"
	ReasonRepeatedFailures InvalidationReason = "repeated_failures"
	ReasonManualRevoke     InvalidationReason = "manual_revoke"
	ReasonSecurityEvent    InvalidationReason = "security_event"
)

type InvalidationRecord 

type InvalidationRecord struct {
	PeerDID       string             `json:"peerDid"`
	Reason        InvalidationReason `json:"reason"`
	InvalidatedAt time.Time          `json:"invalidatedAt"`
}

InvalidationRecord stores details about a session invalidation.

type NonceCache 

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

NonceCache prevents nonce replay attacks by tracking recently seen nonces.

func NewNonceCache 

func NewNonceCache(ttl time.Duration) *NonceCache

NewNonceCache creates a new NonceCache with the given TTL.

func (*NonceCache) CheckAndRecord 

func (nc *NonceCache) CheckAndRecord(nonce []byte) bool

CheckAndRecord returns true if the nonce has NOT been seen before (first occurrence). Returns false if the nonce was already recorded (replay detected). The nonce parameter must be exactly 32 bytes.

func (*NonceCache) Cleanup 

func (nc *NonceCache) Cleanup()

Cleanup removes expired entries older than TTL.

func (*NonceCache) Start 

func (nc *NonceCache) Start()

Start begins periodic cleanup using a ticker goroutine.

func (*NonceCache) Stop 

func (nc *NonceCache) Stop()

Stop halts the periodic cleanup goroutine.

type PendingHandshake 

type PendingHandshake struct {
	PeerID     peer.ID   `json:"peerId"`
	PeerDID    string    `json:"peerDid"`
	RemoteAddr string    `json:"remoteAddr"`
	Timestamp  time.Time `json:"timestamp"`
}

PendingHandshake describes a handshake awaiting user approval.

type SecurityEventHandler 

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

SecurityEventHandler tracks tool execution failures and reputation changes to auto-invalidate sessions when thresholds are exceeded.

func NewSecurityEventHandler 

func NewSecurityEventHandler(
	sessions *SessionStore,
	maxFailures int,
	minTrustScore float64,
	logger *zap.SugaredLogger,
) *SecurityEventHandler

NewSecurityEventHandler creates a handler that auto-invalidates sessions after consecutive tool failures or reputation drops below the threshold.

func (*SecurityEventHandler) OnReputationChange 

func (h *SecurityEventHandler) OnReputationChange(peerDID string, newScore float64)

OnReputationChange invalidates the peer's session if the new score drops below the minimum trust threshold.

func (*SecurityEventHandler) RecordToolFailure 

func (h *SecurityEventHandler) RecordToolFailure(peerDID string)

RecordToolFailure increments the consecutive failure counter for the peer. When the counter reaches maxFailures, the session is auto-invalidated.

func (*SecurityEventHandler) RecordToolSuccess 

func (h *SecurityEventHandler) RecordToolSuccess(peerDID string)

RecordToolSuccess resets the consecutive failure counter for the peer.

type Session 

type Session struct {
	PeerDID           string             `json:"peerDid"`
	Token             string             `json:"token"`
	CreatedAt         time.Time          `json:"createdAt"`
	ExpiresAt         time.Time          `json:"expiresAt"`
	ZKVerified        bool               `json:"zkVerified"`
	Invalidated       bool               `json:"invalidated"`
	InvalidatedReason InvalidationReason `json:"invalidatedReason,omitempty"`
}

Session represents an authenticated peer session.

func (*Session) IsExpired 

func (s *Session) IsExpired() bool

IsExpired reports whether the session has expired.

type SessionAck 

type SessionAck struct {
	Token     string `json:"token"`
	ExpiresAt int64  `json:"expiresAt"`
}

SessionAck is sent by the initiator after verifying the response.

type SessionStore 

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

SessionStore manages authenticated peer sessions with TTL eviction.

func NewSessionStore 

func NewSessionStore(ttl time.Duration) (*SessionStore, error)

NewSessionStore creates a session store with the given TTL.

func (*SessionStore) ActiveSessions 

func (s *SessionStore) ActiveSessions() []*Session

ActiveSessions returns all non-expired, non-invalidated sessions.

func (*SessionStore) Cleanup 

func (s *SessionStore) Cleanup() int

Cleanup removes all expired and invalidated sessions.

func (*SessionStore) Create 

func (s *SessionStore) Create(peerDID string, zkVerified bool) (*Session, error)

Create creates a new session for the given peer DID.

func (*SessionStore) Get 

func (s *SessionStore) Get(peerDID string) *Session

Get returns the session for the given peer DID, or nil if not found/expired/invalidated.

func (*SessionStore) Invalidate 

func (s *SessionStore) Invalidate(peerDID string, reason InvalidationReason)

Invalidate marks a session as invalidated, removes it from active sessions, records the invalidation, and fires the onInvalidate callback.

func (*SessionStore) InvalidateAll 

func (s *SessionStore) InvalidateAll(reason InvalidationReason)

InvalidateAll invalidates all active sessions with the given reason.

func (*SessionStore) InvalidateByCondition 

func (s *SessionStore) InvalidateByCondition(reason InvalidationReason, predicate func(*Session) bool)

InvalidateByCondition invalidates sessions matching the predicate.

func (*SessionStore) InvalidationHistory 

func (s *SessionStore) InvalidationHistory() []InvalidationRecord

InvalidationHistory returns all recorded invalidation events.

func (*SessionStore) Remove 

func (s *SessionStore) Remove(peerDID string)

Remove deletes a session.

func (*SessionStore) SetInvalidationCallback 

func (s *SessionStore) SetInvalidationCallback(fn func(peerDID string, reason InvalidationReason))

SetInvalidationCallback sets a function to be called when a session is invalidated.

func (*SessionStore) Validate 

func (s *SessionStore) Validate(peerDID, token string) bool

Validate checks if a session token is valid for the given peer DID.

type ZKProverFunc 

type ZKProverFunc func(ctx context.Context, challenge []byte) ([]byte, error)

ZKProverFunc generates a ZK ownership proof for the given challenge.

type ZKVerifierFunc 

type ZKVerifierFunc func(ctx context.Context, proof, challenge, publicKey []byte) (bool, error)

ZKVerifierFunc verifies a ZK ownership proof.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.