From 4eda230c293e97a3dd773e0d3990176e0f7d56e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20Mur=C3=A9?= <batolettre@gmail.com>
Date: Mon, 5 Jan 2026 16:33:21 +0100
Subject: [PATCH] crypto: more docs

---
 crypto/_testsuite/testsuite.go | 3 +++
 crypto/hash.go                 | 4 ++++
 crypto/jwk/private.go          | 1 +
 crypto/jwk/public.go           | 1 +
 crypto/options.go              | 5 +++++
 5 files changed, 14 insertions(+)

diff --git a/crypto/_testsuite/testsuite.go b/crypto/_testsuite/testsuite.go
index 7988842..38cd788 100644
--- a/crypto/_testsuite/testsuite.go
+++ b/crypto/_testsuite/testsuite.go
@@ -14,6 +14,7 @@ import (
 	"github.com/MetaMask/go-did-it/crypto"
 )
 
+// TestHarness describes a keypair implementation for the test/bench suites to operate on.
 type TestHarness[PubT crypto.PublicKey, PrivT crypto.PrivateKey] struct {
 	Name string
 
@@ -38,6 +39,7 @@ type TestHarness[PubT crypto.PublicKey, PrivT crypto.PrivateKey] struct {
 	SignatureBytesSize  int
 }
 
+// TestSuite runs a set of tests against a keypair implementation.
 func TestSuite[PubT crypto.PublicKey, PrivT crypto.PrivateKey](t *testing.T, harness TestHarness[PubT, PrivT]) {
 	stats := struct {
 		bytesPubSize  int
@@ -337,6 +339,7 @@ func TestSuite[PubT crypto.PublicKey, PrivT crypto.PrivateKey](t *testing.T, har
 	})
 }
 
+// BenchSuite runs a set of benchmarks on a keypair implementation.
 func BenchSuite[PubT crypto.PublicKey, PrivT crypto.PrivateKey](b *testing.B, harness TestHarness[PubT, PrivT]) {
 	b.Run("GenerateKeyPair", func(b *testing.B) {
 		b.ReportAllocs()
diff --git a/crypto/hash.go b/crypto/hash.go
index fbfc274..4762523 100644
--- a/crypto/hash.go
+++ b/crypto/hash.go
@@ -12,6 +12,7 @@ import (
 // As the standard crypto library prohibits from registering additional hash algorithm (like keccak),
 // below is essentially an extension of that mechanism to allow it.
 
+// Hash is similar to crypto.Hash but can be extended with more values.
 type Hash uint
 
 const (
@@ -50,6 +51,7 @@ func (h Hash) HashFunc() Hash {
 	return h
 }
 
+// String returns the name of the hash function.
 func (h Hash) String() string {
 	if h < maxStdHash {
 		return stdcrypto.Hash(h).String()
@@ -75,6 +77,7 @@ func (h Hash) New() hash.Hash {
 	panic("requested hash function #" + strconv.Itoa(int(h)) + " is unavailable")
 }
 
+// ToVarsigHash returns the corresponding varsig.Hash value.
 func (h Hash) ToVarsigHash() varsig.Hash {
 	if h == MD5SHA1 {
 		panic("no multihash/multicodec value exists for MD5+SHA1")
@@ -85,6 +88,7 @@ func (h Hash) ToVarsigHash() varsig.Hash {
 	panic("requested hash #" + strconv.Itoa(int(h)) + " is unavailable")
 }
 
+// FromVarsigHash converts a varsig.Hash value to the corresponding Hash value.
 func FromVarsigHash(h varsig.Hash) Hash {
 	switch h {
 	case varsig.HashMd4:
diff --git a/crypto/jwk/private.go b/crypto/jwk/private.go
index 4ced0d3..bc4ae03 100644
--- a/crypto/jwk/private.go
+++ b/crypto/jwk/private.go
@@ -15,6 +15,7 @@ import (
 	"github.com/MetaMask/go-did-it/crypto/x25519"
 )
 
+// PrivateJwk is a JWK holding a private key
 type PrivateJwk struct {
 	Privkey crypto.PrivateKey
 }
diff --git a/crypto/jwk/public.go b/crypto/jwk/public.go
index ac5dd41..26c6d8f 100644
--- a/crypto/jwk/public.go
+++ b/crypto/jwk/public.go
@@ -19,6 +19,7 @@ import (
 // - https://www.rfc-editor.org/rfc/rfc7517#section-4 (JWK)
 // - https://www.iana.org/assignments/jose/jose.xhtml#web-key-types (key parameters)
 
+// PublicJwk is a JWK holding a public key
 type PublicJwk struct {
 	Pubkey crypto.PublicKey
 }
diff --git a/crypto/options.go b/crypto/options.go
index b7cda87..ccad4fb 100644
--- a/crypto/options.go
+++ b/crypto/options.go
@@ -4,6 +4,7 @@ import (
 	"github.com/ucan-wg/go-varsig"
 )
 
+// SigningOpts contains the resulting signature configuration.
 type SigningOpts struct {
 	hash            Hash
 	payloadEncoding varsig.PayloadEncoding
@@ -14,6 +15,7 @@ type SigningOpts struct {
 	keyLen uint64
 }
 
+// CollectSigningOptions collects the signing options into a SigningOpts.
 func CollectSigningOptions(opts []SigningOption) SigningOpts {
 	res := SigningOpts{}
 	for _, opt := range opts {
@@ -22,6 +24,7 @@ func CollectSigningOptions(opts []SigningOption) SigningOpts {
 	return res
 }
 
+// HashOrDefault returns the hash algorithm to be used for signatures, or the default if not specified.
 func (opts SigningOpts) HashOrDefault(_default Hash) Hash {
 	if opts.hash == 0 {
 		return _default
@@ -29,6 +32,7 @@ func (opts SigningOpts) HashOrDefault(_default Hash) Hash {
 	return opts.hash
 }
 
+// PayloadEncoding returns the encoding used on the message before signing it.
 func (opts SigningOpts) PayloadEncoding() varsig.PayloadEncoding {
 	if opts.payloadEncoding == 0 {
 		return varsig.PayloadEncodingVerbatim
@@ -36,6 +40,7 @@ func (opts SigningOpts) PayloadEncoding() varsig.PayloadEncoding {
 	return opts.payloadEncoding
 }
 
+// VarsigMatch returns true if the given varsig parameters match the signing options.
 func (opts SigningOpts) VarsigMatch(algo varsig.Algorithm, curve uint64, keyLength uint64) bool {
 	// This is relatively ugly, but we get cyclic import otherwise
 	switch opts.algo {