verificationmethod

package
v1.9.1 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: MIT Imports: 18 Imported by: 3

Documentation

Index

Constants

View Source 
const (
	ReasonSuperseded    = "superseded"
	ReasonKeyCompromise = "keyCompromise"
)

Revocation reasons follow RFC 5280 §5.3.1 (CRL Reason Codes) naming where applicable. Pila keeps a minimal built-in taxonomy with two semantic tiers: 

Soft reasons — credentials signed BEFORE the revoked timestamp remain
  valid. Used for planned key replacements and graceful key retirements.
Hard reasons — invalidate ALL credentials signed by the key, regardless
  of proof.created. Used when the private key is suspected or known to
  be compromised.

Reference: https://www.rfc-editor.org/rfc/rfc5280#section-5.3.1

Variables

This section is empty.

Functions

func DIDFromVerificationMethodURL added in v1.6.0 

func DIDFromVerificationMethodURL(verificationMethodURL string) (string, error)

DIDFromVerificationMethodURL extracts the DID prefix from a verification method URL such as "did:nda:0xabc#key-1". The split is at the first '#'; the URL must start with "did:" — empty input or non-DID URLs return an error.

func DecodeMultibaseKey added in v1.8.0 

func DecodeMultibaseKey(s string) ([]byte, error)

DecodeMultibaseKey decodes a base58btc ('z') multibase string into its raw bytes (including any multicodec prefix).

func DecodeP256PrivMultibase added in v1.8.0 

func DecodeP256PrivMultibase(s string) (*ecdsa.PrivateKey, error)

DecodeP256PrivMultibase decodes a P-256 secret-key Multikey ("z42t...").

func DecodeP256PubMultibase added in v1.8.0 

func DecodeP256PubMultibase(s string) ([]byte, *ecdsa.PublicKey, error)

DecodeP256PubMultibase decodes a P-256 public-key Multikey ("zDnae...") into its raw form (prefix + 33-byte compressed point) and an *ecdsa.PublicKey.

func EncodeMultibaseKey added in v1.8.0 

func EncodeMultibaseKey(raw []byte) string

EncodeMultibaseKey encodes raw bytes as a base58btc ('z') multibase string.

func EncodeP256PubMultibase added in v1.8.0 

func EncodeP256PubMultibase(pub *ecdsa.PublicKey) string

EncodeP256PubMultibase encodes a P-256 public key as a Multikey string.

func EnsureVMAuthorizedForPurpose added in v1.8.0 

func EnsureVMAuthorizedForPurpose(doc *DIDDocument, vmID, purpose string) error

EnsureVMAuthorizedForPurpose mirrors the verifier's strict purpose check on the signing side: the VM must appear in the DID document's relationship array for purpose. Used when a kid is pinned (which otherwise bypasses the purpose-filtered selection), so a signer can't bind a proof to a key that the verifier would reject for that purpose.

func IsHardRevocationReason added in v1.6.0 

func IsHardRevocationReason(reason string) bool

IsHardRevocationReason reports whether the reason indicates a key compromise, in which case verifiers must reject every signature ever produced by the key.

func JWKToHex added in v1.6.0 

func JWKToHex(jwk *JWK) (string, error)

JWKToHex converts a secp256k1 JWK to its uncompressed hex representation (0x04 || X || Y). Useful when callers already have a JWK in hand and want to produce a hex public key without going through any DID resolver.

func NormalizeVerificationMethodURL added in v1.6.0 

func NormalizeVerificationMethodURL(did, kid string) string

NormalizeVerificationMethodURL turns a caller-supplied kid into a full "did#fragment" URL. Accepts three input forms:

  • "did:example:123#key-1" → returned as-is (already full URL)
  • "#key-1" → "<did>#key-1"
  • "key-1" → "<did>#key-1"

func P256PubFromMultikeyBytes added in v1.8.0 

func P256PubFromMultikeyBytes(raw []byte) (*ecdsa.PublicKey, error)

P256PubFromMultikeyBytes decodes raw Multikey bytes (prefix + compressed point) of a P-256 public key into an *ecdsa.PublicKey.

func P256PubFromVM added in v1.8.0 

func P256PubFromVM(vm *VerificationMethodEntry) (*ecdsa.PublicKey, error)

P256PubFromVM extracts the P-256 public key from a verification method, accepting either `publicKeyJwk` (JsonWebKey2020) or the W3C `publicKeyMultibase` (Multikey) form.

func P256PubKeyFromJWK added in v1.8.0 

func P256PubKeyFromJWK(jwk *JWK) (*ecdsa.PublicKey, error)

P256PubKeyFromJWK builds an *ecdsa.PublicKey on the P-256 curve from a JWK with kty=EC and crv=P-256. Used by the ecdsa-sd-2023 verifier.

func P256PubToMultikeyBytes added in v1.8.0 

func P256PubToMultikeyBytes(compressed []byte) []byte

P256PubToMultikeyBytes prepends the p256-pub multicodec prefix to a 33-byte compressed SEC1 point, producing the raw Multikey byte form.

func PublicKeyHexFromVM added in v1.6.0 

func PublicKeyHexFromVM(vm *VerificationMethodEntry) (string, error)

PublicKeyHexFromVM returns the public key hex material for the given VM. It supports both `publicKeyHex` and `publicKeyJwk` encodings.

The returned value may include or omit the 0x prefix depending on source; callers that decode should accept either (most helpers in this repo trim it).

func RSAPubKeyFromJWK added in v1.8.0 

func RSAPubKeyFromJWK(jwk *JWK) (*rsa.PublicKey, error)

RSAPubKeyFromJWK builds an *rsa.PublicKey from a JWK with kty=RSA.

func ResolveVerificationMethodURL added in v1.6.0 

func ResolveVerificationMethodURL(ctx context.Context, did, purpose string, resolver ResolverProvider) (string, error)

ResolveVerificationMethodURL returns the full verification method URL (kid) for signing/verifying given DID and purpose by reading the DID document and picking the latest active VM in the relationship array for the given purpose.

func ResolveVerificationMethodURLForKey added in v1.8.0 

func ResolveVerificationMethodURLForKey(ctx context.Context, did, purpose string, kind KeyKind, resolver ResolverProvider) (string, error)

ResolveVerificationMethodURLForKey is like ResolveVerificationMethodURL but picks the latest active VM whose key matches kind, so the resolved VM is compatible with the signer's cryptosuite.

func Secp256k1PubFromHex added in v1.8.0 

func Secp256k1PubFromHex(h string) (*ecdsa.PublicKey, error)

Secp256k1PubFromHex parses an uncompressed (0x04||X||Y) hex public key into an *ecdsa.PublicKey on the secp256k1 curve. The 0x prefix is optional. Pair it with PublicKeyHexFromVM to resolve a secp256k1 key from a verification method.

func VMIsP256 added in v1.8.0 

func VMIsP256(vm *VerificationMethodEntry) bool

func VMIsRSA added in v1.8.0 

func VMIsRSA(vm *VerificationMethodEntry) bool

func VMIsSecp256k1 added in v1.8.0 

func VMIsSecp256k1(vm *VerificationMethodEntry) bool

VMIsSecp256k1 matches an EC secp256k1 JWK or a publicKeyHex (the EcdsaSecp256k1VerificationKey2019 representation). P-256 keys never use publicKeyHex.

Types

type DIDDocument 

type DIDDocument struct {
	Context             []string                  `json:"@context"`
	ID                  string                    `json:"id"`
	VerificationMethod  []VerificationMethodEntry `json:"verificationMethod"`
	Authentication      []string                  `json:"authentication"`
	AssertionMethod     []string                  `json:"assertionMethod"`
	Controller          interface{}               `json:"controller"` // string or []string
	DIDDocumentMetadata map[string]interface{}    `json:"didDocumentMetadata"`
}

DIDDocument represents the structure of a resolved DID Document. Only the relationship arrays Pila exposes (`authentication`, `assertionMethod`) are typed; other W3C-defined arrays (keyAgreement, capabilityInvocation, capabilityDelegation) are intentionally omitted — see Pila's multi-VM design Option A.

func NewDIDDocument added in v1.8.0 

func NewDIDDocument(did string, vms ...VerificationMethodEntry) *DIDDocument

NewDIDDocument builds a DID document exposing vms, listing every VM under both assertionMethod and authentication.

type HTTPResolver added in v1.6.0 

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

HTTPResolver fetches DID Documents from a Pila-style HTTP DID resolver endpoint (`baseURL/<did>` returning JSON). It implements ResolverProvider with a single method — all higher-level operations (VM selection, key extraction, purpose checks) live as free functions in this package so callers that already have a resolved document (e.g. from gRPC) can use them without going through HTTP.

func NewHTTPResolver added in v1.6.0 

func NewHTTPResolver(baseURL string, opts ...Option) *HTTPResolver

NewHTTPResolver creates an HTTP-backed ResolverProvider.

func (*HTTPResolver) ResolveDocument added in v1.6.0 

func (r *HTTPResolver) ResolveDocument(ctx context.Context, did string) (*DIDDocument, error)

ResolveDocument fetches and parses the DID Document for the given DID. Returns an error when did is empty, the HTTP call fails, the response status is non-2xx, or the body fails to decode as a DID Document.

type JWK 

type JWK struct {
	Kty string `json:"kty"`           // "EC" or "RSA"
	Crv string `json:"crv,omitempty"` // EC curve ("secp256k1")
	X   string `json:"x,omitempty"`   // EC X coordinate (base64url, raw)
	Y   string `json:"y,omitempty"`   // EC Y coordinate (base64url, raw)
	N   string `json:"n,omitempty"`   // RSA modulus (base64url)
	E   string `json:"e,omitempty"`   // RSA public exponent (base64url)
}

JWK represents a JSON Web Key. It supports EC (secp256k1) and RSA keys.

type KeyKind added in v1.8.0 

type KeyKind int

KeyKind identifies the key type a verification method holds, so VM selection can match the signer's key. 

const (
	KeySecp256k1 KeyKind = iota
	KeyRSA
	KeyP256
)

func VMKeyKind added in v1.8.0 

func VMKeyKind(vm *VerificationMethodEntry) (KeyKind, bool)

VMKeyKind reports the key kind a verification method holds, and whether it was recognized. Signing uses it to pick the cryptosuite from the bound key.

func (KeyKind) String added in v1.8.0 

func (k KeyKind) String() string

type Option added in v1.5.8 

type Option func(*HTTPResolver)

Option configures HTTPResolver construction.

func WithHTTPClient added in v1.5.8 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient overrides the default HTTP client (10s timeout). Pass nil to keep the default.

type ResolverProvider added in v1.5.8 

type ResolverProvider interface {
	ResolveDocument(ctx context.Context, did string) (*DIDDocument, error)
}

ResolverProvider resolves a DID Document by DID.

Implementations should only concern themselves with fetching/parsing a DID document. Higher-level operations (VM selection, key extraction, purpose checks) are provided as helper functions in this package.

ctx is required so callers can propagate cancellation and deadlines to the underlying I/O (HTTP, gRPC, etc.). Implementations that do no I/O (e.g. an in-memory test resolver) may ignore it.

type StaticResolver added in v1.5.8 

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

StaticResolver is an in-memory ResolverProvider backed by a fixed set of DID documents. It does no I/O, so it is ideal for tests and offline use — for example to verify credentials signed with key types the production DID resolver does not yet publish (RSA, P-256).

func NewStaticResolver added in v1.5.8 

func NewStaticResolver(docs ...*DIDDocument) *StaticResolver

NewStaticResolver builds a StaticResolver from the given documents, keyed by each document's ID.

func (*StaticResolver) Add added in v1.8.0 

func (r *StaticResolver) Add(doc *DIDDocument)

Add registers (or replaces) a DID document, keyed by its ID.

func (*StaticResolver) ResolveDocument added in v1.8.0 

func (r *StaticResolver) ResolveDocument(_ context.Context, did string) (*DIDDocument, error)

ResolveDocument returns the registered document for did, or an error if none.

type VerificationMethodEntry 

type VerificationMethodEntry struct {
	ID                 string     `json:"id"`
	Type               string     `json:"type"`
	Controller         string     `json:"controller"`
	PublicKeyHex       string     `json:"publicKeyHex,omitempty"`
	PublicKeyJwk       *JWK       `json:"publicKeyJwk,omitempty"`
	PublicKeyMultibase string     `json:"publicKeyMultibase,omitempty"`
	Revoked            *time.Time `json:"revoked,omitempty"`
	RevocationReason   string     `json:"revocationReason,omitempty"`
}

VerificationMethodEntry represents a single verification method in a DID Document. Conforms to W3C CID 1.0 §2.2 — id/type/controller plus verification material (publicKeyHex for EcdsaSecp256k1VerificationKey2019, publicKeyJwk for JWK-encoded keys).

Revoked and RevocationReason are Pila extensions following W3C MAY guidance for additional properties; see revocation.go for taxonomy.

func FindVerificationMethod added in v1.6.0 

func FindVerificationMethod(doc *DIDDocument, verificationMethodURL string) (*VerificationMethodEntry, error)

FindVerificationMethod returns the VerificationMethodEntry whose Id equals verificationMethodURL. The lookup is by exact full-URL match; callers that need fragment-form matching should normalize first.

func NewP256VM added in v1.8.0 

func NewP256VM(did, fragment string, pub *ecdsa.PublicKey) VerificationMethodEntry

NewP256VM builds a JsonWebKey2020 verification method from a P-256 public key. Used by ecdsa-sd-2023.

func NewRSAVM added in v1.8.0 

func NewRSAVM(did, fragment string, pub *rsa.PublicKey) VerificationMethodEntry

NewRSAVM builds a JsonWebKey2020 verification method from an RSA public key. Used by JsonWebSignature2020.

func NewSecp256k1VM added in v1.8.0 

func NewSecp256k1VM(did, fragment, pubKeyHex string) VerificationMethodEntry

NewSecp256k1VM builds an EcdsaSecp256k1VerificationKey2019 verification method from an uncompressed public key hex (0x04||X||Y). Used by ecdsa-rdfc-2019.

func ResolveSigningVM added in v1.8.0 

func ResolveSigningVM(ctx context.Context, did, purpose, pinnedKid string, resolver ResolverProvider) (*VerificationMethodEntry, string, error)

ResolveSigningVM resolves the DID document and returns the verification method to sign with: the pinned kid when given, otherwise the latest active VM for purpose. The returned entry lets the caller read the key type and pick the cryptosuite.

func SelectLatestActiveVMForKey added in v1.8.0 

func SelectLatestActiveVMForKey(doc *DIDDocument, purpose string, kind KeyKind) (*VerificationMethodEntry, error)

SelectLatestActiveVMForKey is like SelectLatestActiveVMForPurpose but only considers verification methods holding a key of the given kind — so an RSA signer never binds its proof to a secp256k1 VM (or vice versa) on a DID with keys of several kinds in the same relationship array.

func SelectLatestActiveVMForPurpose added in v1.6.0 

func SelectLatestActiveVMForPurpose(doc *DIDDocument, purpose string) (*VerificationMethodEntry, error)

SelectLatestActiveVMForPurpose picks the active verification method that holds the given purpose ("authentication" or "assertionMethod") and has the highest sequential `#key-N` index in the relationship array.

func SelectVMForPurpose added in v1.6.0 

func SelectVMForPurpose(doc *DIDDocument, purpose, kid string) (*VerificationMethodEntry, error)

SelectVMForPurpose chooses a verification method from a resolved DID Document, preferring an explicit kid when provided.

  • kid empty (legacy tokens) → fall back to SelectLatestActiveVMForPurpose.
  • kid non-empty → look up by id (full URL "did:...#key-1", "#key-1", or bare "key-1"); the returned VM may be revoked. Apply revocation timing and purpose authorization checks separately at the verifier.

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.