identity

Documentation

Overview

Package identity provides ATProto identity resolution — resolving DIDs to DID documents and handles to DIDs with bi-directional verification.

Index

• Variables
• type Cache
  • func NewLRUCache(capacity int, ttl time.Duration) Cache
• type DIDDocument
  • func ParseDIDDocument(data []byte) (*DIDDocument, error)
• type DefaultResolver
  • func (r *DefaultResolver) ResolveDID(ctx context.Context, did atmos.DID) (*DIDDocument, error)
  • func (r *DefaultResolver) ResolveHandle(ctx context.Context, handle atmos.Handle) (atmos.DID, error)
• type Directory
  • func (d *Directory) Lookup(ctx context.Context, id atmos.ATIdentifier) (*Identity, error)
  • func (d *Directory) LookupDID(ctx context.Context, did atmos.DID) (*Identity, error)
  • func (d *Directory) LookupHandle(ctx context.Context, handle atmos.Handle) (*Identity, error)
  • func (d *Directory) Purge(ctx context.Context, did atmos.DID)
• type Identity
  • func IdentityFromDocument(doc *DIDDocument) (*Identity, error)
  • func (id *Identity) PDSEndpoint() string
  • func (id *Identity) PublicKey() (crypto.PublicKey, error)
• type Key
• type Resolver
• type Service
• type ServiceEndpoint
• type VerificationMethod

Variables

var (
	// ErrDIDNotFound indicates the DID document could not be found.
	ErrDIDNotFound = errors.New("identity: DID not found")
	// ErrHandleNotFound indicates no DID was found for the handle.
	ErrHandleNotFound = errors.New("identity: handle not found")
	// ErrUnsupportedDIDMethod indicates the DID method is not did:plc or did:web.
	ErrUnsupportedDIDMethod = errors.New("identity: unsupported DID method")
)

Types

type Cache

type Cache interface {
	// Get retrieves a cached identity by key. Returns false if not found or expired.
	Get(ctx context.Context, key string) (*Identity, bool)
	// Set stores an identity in the cache.
	Set(ctx context.Context, key string, val *Identity)
	// Delete removes an identity from the cache.
	Delete(ctx context.Context, key string)
}

Cache is a bring-your-own cache interface for identity resolution.

func NewLRUCache

func NewLRUCache(capacity int, ttl time.Duration) Cache

NewLRUCache returns a Cache backed by an in-memory LRU with the given capacity and TTL. Capacity must be >= 1.

type DIDDocument

type DIDDocument struct {
	ID                 string               `json:"id"`
	AlsoKnownAs        []string             `json:"alsoKnownAs"`
	VerificationMethod []VerificationMethod `json:"verificationMethod"`
	Service            []Service            `json:"service"`
}

DIDDocument is the raw JSON structure from a PLC directory or did:web resolution.

func ParseDIDDocument

func ParseDIDDocument(data []byte) (*DIDDocument, error)

ParseDIDDocument parses a DID document from JSON bytes.

type DefaultResolver

type DefaultResolver struct {
	HTTPClient            gt.Option[*http.Client]
	PLCURL                gt.Option[string]
	SkipDNSDomainSuffixes []string // e.g. [".bsky.social"] — HTTP-only for these
	// contains filtered or unexported fields
}

DefaultResolver resolves DIDs and handles via network requests.

func (*DefaultResolver) ResolveDID

func (r *DefaultResolver) ResolveDID(ctx context.Context, did atmos.DID) (*DIDDocument, error)

ResolveDID fetches the DID document for the given DID.

func (*DefaultResolver) ResolveHandle

func (r *DefaultResolver) ResolveHandle(ctx context.Context, handle atmos.Handle) (atmos.DID, error)

ResolveHandle resolves a handle to a DID. If the handle matches a SkipDNSDomainSuffixes entry, only HTTP is used. Otherwise DNS and HTTP are raced in parallel, returning whichever succeeds first.

type Directory

type Directory struct {
	Resolver Resolver
	Cache    Cache // nil = no caching
	// contains filtered or unexported fields
}

Directory resolves identities with bi-directional verification and optional caching.

func (*Directory) Lookup

func (d *Directory) Lookup(ctx context.Context, id atmos.ATIdentifier) (*Identity, error)

Lookup resolves an ATIdentifier (DID or handle) to a verified Identity.

func (*Directory) LookupDID

func (d *Directory) LookupDID(ctx context.Context, did atmos.DID) (*Identity, error)

LookupDID resolves a DID to a verified Identity.

func (*Directory) LookupHandle

func (d *Directory) LookupHandle(ctx context.Context, handle atmos.Handle) (*Identity, error)

LookupHandle resolves a handle to a verified Identity.

func (*Directory) Purge

func (d *Directory) Purge(ctx context.Context, did atmos.DID)

Purge removes the cached identity for a DID, forcing the next lookup to re-resolve from the network. This is useful when a signing key rotation is detected (e.g. service auth signature verification fails).

type Identity

type Identity struct {
	DID      atmos.DID
	Handle   atmos.Handle
	Keys     map[string]Key
	Services map[string]ServiceEndpoint
}

Identity is the resolved, verified identity of an ATProto account.

func IdentityFromDocument

func IdentityFromDocument(doc *DIDDocument) (*Identity, error)

IdentityFromDocument extracts an Identity from a parsed DID document.

func (*Identity) PDSEndpoint

func (id *Identity) PDSEndpoint() string

PDSEndpoint returns the PDS URL for this identity, or empty string if not present.

func (*Identity) PublicKey

func (id *Identity) PublicKey() (crypto.PublicKey, error)

PublicKey parses and returns the atproto signing key for this identity.

type Key

type Key struct {
	Type      string
	Multibase string
}

Key is a verification key extracted from a DID document.

type Resolver

type Resolver interface {
	// ResolveDID fetches the DID document for the given DID.
	ResolveDID(ctx context.Context, did atmos.DID) (*DIDDocument, error)
	// ResolveHandle resolves a handle to its DID via DNS or HTTP.
	ResolveHandle(ctx context.Context, handle atmos.Handle) (atmos.DID, error)
}

Resolver performs low-level network resolution without verification or caching.

type Service

type Service struct {
	ID              string `json:"id"`
	Type            string `json:"type"`
	ServiceEndpoint string `json:"serviceEndpoint"`
}

Service is a service entry in a DID document.

type ServiceEndpoint

type ServiceEndpoint struct {
	Type string
	URL  string
}

ServiceEndpoint is a service extracted from a DID document.

type VerificationMethod

type VerificationMethod struct {
	ID                 string `json:"id"`
	Type               string `json:"type"`
	Controller         string `json:"controller"`
	PublicKeyMultibase string `json:"publicKeyMultibase"`
}

VerificationMethod is a key entry in a DID document.