did

Documentation

Overview

Package did provides utilities for parsing and working with DID identifiers. Supports did:web (RFC-002 §6.1) and did:key (RFC-002 §6.6) methods. See RFC-002: Trust Badge Specification v1.1.

Index

• Constants
• Variables
• func NewAgentDID(domain, agentID string) string
• func NewCapiscIOAgentDID(agentID string) string
• func NewKeyDID(publicKey []byte) string
• func PublicKeyFromKeyDID(didStr string) (ed25519.PublicKey, error)
• type DID
  • func Parse(did string) (*DID, error)
  • func (d *DID) DocumentURL() string
  • func (d *DID) GetPublicKey() ed25519.PublicKey
  • func (d *DID) IsAgentDID() bool
  • func (d *DID) IsKeyDID() bool
  • func (d *DID) IsWebDID() bool
  • func (d *DID) String() string
• type Document
• type JWK
• type VerificationMethod
• type WebResolver
  • func (r *WebResolver) Resolve(ctx context.Context, didStr string, kid string) (crypto.PublicKey, error)

Constants

const (
	// Ed25519MulticodecPrefix is the multicodec prefix for Ed25519 public keys (0xed01)
	Ed25519MulticodecPrefix = 0xed01

	// Ed25519PublicKeySize is the size of an Ed25519 public key in bytes
	Ed25519PublicKeySize = 32
)

Multicodec constants for did:key

const DefaultCacheTTL = 5 * time.Minute

DefaultCacheTTL is the default cache duration for resolved documents.

const DefaultDomain = "registry.capisc.io"

DefaultDomain is the default domain for CapiscIO-hosted agents.

const DefaultMaxDocSize = 64 * 1024

DefaultMaxDocSize is the maximum DID document size (64KB).

const DefaultResolveTimeout = 10 * time.Second

DefaultResolveTimeout is the default HTTP timeout for DID document fetches.

Variables

var (
	ErrInvalidDID         = errors.New("invalid DID format")
	ErrUnsupportedMethod  = errors.New("unsupported DID method (only did:web and did:key supported)")
	ErrMissingAgentID     = errors.New("missing agent ID in DID")
	ErrInvalidKeyDID      = errors.New("invalid did:key format")
	ErrUnsupportedKeyType = errors.New("unsupported key type in did:key (only Ed25519 supported)")
)

Common errors returned by this package.

var (
	ErrSSRFBlocked       = errors.New("SSRF: did:web target resolves to blocked address")
	ErrHTTPRequired      = errors.New("did:web requires HTTPS (HTTP not allowed in production)")
	ErrDocumentTooLarge  = errors.New("DID document exceeds maximum size")
	ErrKeyNotFound       = errors.New("key ID not found in DID document")
	ErrUnsupportedVMType = errors.New("unsupported verification method type")
	ErrDocumentFetch     = errors.New("failed to fetch DID document")
)

WebResolver errors.

Functions

func NewAgentDID

func NewAgentDID(domain, agentID string) string

NewAgentDID constructs a did:web identifier for an agent.

Parameters:

• domain: The domain hosting the agent (e.g., "registry.capisc.io")
• agentID: The unique agent identifier (e.g., "my-agent-001")

Returns: did:web:<domain>:agents:<agentID>

func NewCapiscIOAgentDID

func NewCapiscIOAgentDID(agentID string) string

NewCapiscIOAgentDID constructs a did:web for an agent on the CapiscIO registry. Shorthand for NewAgentDID(DefaultDomain, agentID).

func NewKeyDID

func NewKeyDID(publicKey []byte) string

NewKeyDID constructs a did:key identifier from an Ed25519 public key. Format: did:key:z<base58btc(0xed01 || public_key)>

Parameters:

• publicKey: Ed25519 public key (32 bytes)

Returns: did:key:z6Mk... formatted DID string

func PublicKeyFromKeyDID

func PublicKeyFromKeyDID(didStr string) (ed25519.PublicKey, error)

PublicKeyFromKeyDID extracts the Ed25519 public key from a did:key identifier. Returns the 32-byte public key or an error if the DID is invalid.

Types

type DID

type DID struct {
	// Method is the DID method ("web" or "key").
	Method string

	// Domain is the domain hosting the DID Document (did:web only).
	Domain string

	// Path segments after the domain (did:web only, e.g., ["agents", "my-agent-001"]).
	PathSegments []string

	// AgentID is the agent identifier (did:web only, extracted from path).
	AgentID string

	// PublicKey is the Ed25519 public key (did:key only, 32 bytes).
	PublicKey []byte

	// Raw is the original DID string.
	Raw string
}

DID represents a parsed DID identifier. Supports both did:web and did:key methods.

For did:web: did:web:<domain>:agents:<agent-id> For did:key: did:key:z<base58btc(multicodec || public_key)>

func Parse

func Parse(did string) (*DID, error)

Parse parses a DID identifier into its components. Supports both did:web and did:key methods.

Returns ErrInvalidDID if the format is invalid. Returns ErrUnsupportedMethod if the method is not "web" or "key".

Examples:

• did:web:registry.capisc.io:agents:my-agent-001
• did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

func (*DID) DocumentURL

func (d *DID) DocumentURL() string

DocumentURL returns the HTTPS URL for the DID Document per did:web spec. did:web:registry.capisc.io:agents:my-agent-001

→ https://registry.capisc.io/agents/my-agent-001/did.json

Returns empty string for did:key (no remote document). Uses HTTP when the hostname is "localhost" or "127.0.0.1", HTTPS otherwise.

func (*DID) GetPublicKey

func (d *DID) GetPublicKey() ed25519.PublicKey

GetPublicKey returns the Ed25519 public key for did:key identifiers. Returns nil for did:web identifiers.

func (*DID) IsAgentDID

func (d *DID) IsAgentDID() bool

IsAgentDID returns true if the DID follows the CapiscIO agent DID pattern. Pattern: did:web:<domain>:agents:<id>

func (*DID) IsKeyDID

func (d *DID) IsKeyDID() bool

IsKeyDID returns true if this is a did:key identifier.

func (*DID) IsWebDID

func (d *DID) IsWebDID() bool

IsWebDID returns true if this is a did:web identifier.

func (*DID) String

func (d *DID) String() string

String returns the canonical DID string.

type Document

type Document struct {
	ID                 string               `json:"id"`
	VerificationMethod []VerificationMethod `json:"verificationMethod"`
}

Document represents a DID Document (W3C DID Core §4). Only the fields needed for key resolution are included.

type JWK

type JWK struct {
	Kty string `json:"kty"`
	Crv string `json:"crv"`
	X   string `json:"x"` // base64url-encoded public key
}

JWK represents a JSON Web Key (RFC 7517). Only Ed25519 (OKP curve) is currently supported.

type VerificationMethod

type VerificationMethod struct {
	ID                 string `json:"id"`
	Type               string `json:"type"`
	Controller         string `json:"controller"`
	PublicKeyMultibase string `json:"publicKeyMultibase,omitempty"`
	PublicKeyJwk       *JWK   `json:"publicKeyJwk,omitempty"`
}

VerificationMethod represents a key in a DID Document.

type WebResolver

type WebResolver struct {
	// Client is the HTTP client to use. If nil, a default client with
	// SSRF-safe dialer and timeout is created.
	// WARNING: Setting a custom Client bypasses SSRF protections.
	// UnsafeAllowCustomClient must be true to use a custom Client.
	Client *http.Client

	// UnsafeAllowCustomClient must be set to true when providing a custom Client.
	// This is a safety gate to prevent accidental SSRF bypass.
	UnsafeAllowCustomClient bool

	// MaxDocSize is the maximum response body size in bytes.
	// Default: 64KB.
	MaxDocSize int

	// CacheTTL is the duration to cache resolved documents.
	// Default: 5 minutes. Set to negative value to disable caching.
	CacheTTL time.Duration

	// AllowHTTP allows HTTP (non-TLS) for testing. MUST be false in production.
	AllowHTTP bool
	// contains filtered or unexported fields
}

WebResolver resolves did:web identifiers by fetching DID documents over HTTPS.

func (*WebResolver) Resolve

func (r *WebResolver) Resolve(ctx context.Context, didStr string, kid string) (crypto.PublicKey, error)

Resolve fetches the DID document for a did:web identifier and extracts the public key matching the given key ID fragment.