Documentation
¶
Overview ¶
Package auth implements the /ynp/auth/1.0.0 libp2p handshake that lets a node prove who it is before a peer accepts its restricted streams (notably the burn/mint receipt protocols).
The handshake is a single round trip: the Server sends a random nonce (AuthChallenge); the Client signs it and returns an AuthResponse. Two roles share the wire:
Operator — the client signs keccak256(nonce) with a secp256k1 operator key and sets Address. The server ecrecovers, matches the recovered address to the claimed one, and checks it against an operator allow-list. Proves the peer holds a key on the signer set; the gate for receipt streams.
Passive — the client leaves Address empty and signs a domain-separated nonce with its libp2p identity key. The server verifies against the connection's remote public key. Proves the peer controls the libp2p identity it dials from — no operator key, no allow-list — for gateway-safe / read paths.
The package owns no host.Host: Server.Register installs a handler on a caller-built host (Server satisfies protocol.Registrar), and Client dials over one.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AllowList ¶
type AllowList map[string]struct{}
AllowList is the operator allow-list: a set of lowercased hex addresses. A nil or empty AllowList disables the operator gate — any well-formed operator signature is accepted (useful for early devnet). Passive auth is never gated by the allow-list.
func ParseAllowListCSV ¶
ParseAllowListCSV turns "0xabc..,0xdef.." into an AllowList. Empty input yields an empty set (gate disabled). Malformed entries are skipped.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client runs the dialing side of the auth handshake. It mirrors Server: Server.HandleAuth verifies what Client.Authenticate produces.
func NewClient ¶
func NewClient(opts ClientOpts) *Client
NewClient returns a Client configured by opts.
func (*Client) Authenticate ¶
Authenticate runs the handshake against pid over h. With opts.Signer it performs operator auth; otherwise passive auth with opts.IdentityKey. The remote's HandleAuth marks us authenticated on success.
type ClientOpts ¶
type ClientOpts struct {
// Signer is a secp256k1 operator key. When set, runs operator auth.
Signer sign.Signer
// IdentityKey is the libp2p identity private key. Used for passive auth
// when Signer is nil.
IdentityKey libp2pcrypto.PrivKey
}
ClientOpts selects the role for Authenticate. Exactly one of Signer (operator) or IdentityKey (passive) must be set; Signer takes precedence if both are present.
type Result ¶
type Result struct {
// Address is the recovered 0x-prefixed operator address; empty for passive.
Address string
Role Role
}
Result holds the outcome of a successful authentication.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server handles inbound auth streams: it issues a nonce, verifies the response as operator or passive, and reports each success via an onAuth callback.
func NewServer ¶
NewServer returns a Server gated by allow (nil/empty disables the operator gate). onAuth, if non-nil, is invoked with the connection and Result after each successful handshake — the caller binds whatever "authenticated" means in its world (e.g. marking the connection so receipt streams pass their gate). The connection is passed (not just the peer ID) so the caller can key auth state per-connection, matching libp2p's connection lifetime.
func (*Server) HandleAuth ¶
HandleAuth is the stream handler for /ynp/auth/1.0.0.
Source Files