add a GHA workflow to run the tests

.github/workflows/gotest.yml

@@ -0,0 +1,27 @@
+on: [push, pull_request]
+name: Go Test
+
+jobs:
+  unit:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ "ubuntu" ]
+        go: [ "1.23.x", "1.24.x"]
+    env:
+      COVERAGES: ""
+    runs-on: ${{ matrix.os }}-latest
+    name: ${{ matrix.os}} (go ${{ matrix.go }})
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+      - name: Go information
+        run: |
+          go version
+          go env
+      - name: Run tests
+        run: go test -v ./...
+      - name: Check formatted
+        run: gofmt -l .

LICENSE

@@ -0,0 +1,25 @@
+The contents of this repository are Copyright (c) corresponding authors and
+contributors, licensed under the `Permissive License Stack` meaning either of:
+
+- Apache-2.0 Software License: https://www.apache.org/licenses/LICENSE-2.0
+  ([...4tr2kfsq](https://dweb.link/ipfs/bafkreiankqxazcae4onkp436wag2lj3ccso4nawxqkkfckd6cg4tr2kfsq))
+
+- MIT Software License: https://opensource.org/licenses/MIT
+  ([...vljevcba](https://dweb.link/ipfs/bafkreiepofszg4gfe2gzuhojmksgemsub2h4uy2gewdnr35kswvljevcba))
+
+You may not use the contents of this repository except in compliance
+with one of the listed Licenses. For an extended clarification of the
+intent behind the choice of Licensing please refer to
+https://protocol.ai/blog/announcing-the-permissive-license-stack/
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the terms listed in this notice is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied. See each License for the specific language
+governing permissions and limitations under that License.
+
+<!--- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+
+`SPDX-License-Identifier: Apache-2.0 OR MIT`
+
+Verbatim copies of both licenses are included in the LICENSE-APACHE-2.0 and LICENSE-MIT files.

LICENSE-APACHE-2.0

@@ -1,35 +1,6 @@
-The contents of this repository are Copyright (c) corresponding authors and
-contributors, licensed under the `Permissive License Stack` meaning either of:
-
-- Apache-2.0 Software License: https://www.apache.org/licenses/LICENSE-2.0
-  ([...4tr2kfsq](https://dweb.link/ipfs/bafkreiankqxazcae4onkp436wag2lj3ccso4nawxqkkfckd6cg4tr2kfsq))
-
-- MIT Software License: https://opensource.org/licenses/MIT
-  ([...vljevcba](https://dweb.link/ipfs/bafkreiepofszg4gfe2gzuhojmksgemsub2h4uy2gewdnr35kswvljevcba))
-
-You may not use the contents of this repository except in compliance
-with one of the listed Licenses. For an extended clarification of the
-intent behind the choice of Licensing please refer to
-https://protocol.ai/blog/announcing-the-permissive-license-stack/
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the terms listed in this notice is distributed on
-an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
-either express or implied. See each License for the specific language
-governing permissions and limitations under that License.
-
-<!--- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-
-`SPDX-License-Identifier: Apache-2.0 OR MIT`
-
-Verbatim copies of both licenses are included below:
-
-<details><summary>Apache-2.0 Software License</summary>
-
-```
                                  Apache License
                            Version 2.0, January 2004
-                        https://www.apache.org/licenses/
+                        http://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -203,30 +174,28 @@ Verbatim copies of both licenses are included below:
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
-```
 
-</details>
+   APPENDIX: How to apply the Apache License to your work.
 
-<details><summary>MIT Software License</summary>
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
 
-```
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   Copyright 2025 UCAN Working Group - All right reserved
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-```
+       http://www.apache.org/licenses/LICENSE-2.0
 
-</details>
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 UCAN Working Group - All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -12,43 +12,6 @@ Include the `go-varsig` library by running the following command:
 go get github.com/ucan-wg/go-varsig@latest
 ```
 
-## Quickstart
-
-```go
-func ExampleDecode() {
-	example, err := base64.RawStdEncoding.DecodeString("NAHtAe0BE3E")
-	handleErr(err)
-
-	vs, err := varsig.Decode(example)
-	handleErr(err)
-
-	fmt.Printf("%T\n", vs)
-	fmt.Printf("Algorithm: %d\n", vs.Algorithm())
-	fmt.Printf("Hash: %d\n", vs.Hash())
-	fmt.Printf("PayloadEncoding: %d\n", vs.PayloadEncoding())
-
-	// Output:
-	// varsig.EdDSAVarsig
-	// Algorithm: 237
-	// Hash: 19
-	// PayloadEncoding: 3
-}
-
-func ExampleEncode() {
-	edDSAVarsig := varsig.NewEdDSAVarsig(
-		varsig.CurveEd25519,
-		varsig.HashSha2_512,
-		varsig.PayloadEncodingDAGCBOR,
-	)
-
-	b64 := base64.RawStdEncoding.EncodeToString(edDSAVarsig.Encode())
-	fmt.Print(b64)
-
-	// Output:
-	// NAHtAe0BE3E
-}
-```
-
 ## Documentation
 
 Documentation for this library is provided as Go docs at

common_test.go

@@ -115,7 +115,7 @@ func TestRoundTrip(t *testing.T) {
 			require.NoError(t, err)
 
 			require.Equal(t, tc.varsig.Version(), rt.Version())
-			require.Equal(t, tc.varsig.Algorithm(), rt.Algorithm())
+			require.Equal(t, tc.varsig.Discriminator(), rt.Discriminator())
 			require.Equal(t, tc.varsig.PayloadEncoding(), rt.PayloadEncoding())
 
 			switch vs := tc.varsig.(type) {

constant.go

@@ -173,14 +173,14 @@ func EncodePayloadEncoding(enc PayloadEncoding) []byte {
 	return res
 }
 
-// Algorithm is (usually) the value representing the public key type of
+// Discriminator is (usually) the value representing the public key type of
 // the algorithm used to create the signature.
 //
 // There is no set list of constants here, nor is there a decode function
 // as the author of an implementation should include the constant with the
 // implementation, and the decoding is handled by the Handler, which uses
-// the Algorithm to choose the correct implementation.  Also note that
-// some of the Algorithm values for a specific implementation have
+// the Discriminator to choose the correct implementation.  Also note that
+// some of the Discriminator values for a specific implementation have
 // changed between varsig v0 and v1, so it's possible to have more than one
 // constant defined per implementation.
-type Algorithm uint64
+type Discriminator uint64

ecdsa.go

@@ -5,8 +5,8 @@ import (
 	"fmt"
 )
 
-// AlgorithmECDSA is the value specifying an ECDSA signature.
-const AlgorithmECDSA = Algorithm(0xec)
+// DiscriminatorECDSA is the value specifying an ECDSA signature.
+const DiscriminatorECDSA = Discriminator(0xec)
 
 // ECDSACurve are values that specify which ECDSA curve is used when
 // generating the signature.
@@ -51,7 +51,7 @@ type ECDSAVarsig struct {
 func NewECDSAVarsig(curve ECDSACurve, hashAlgorithm Hash, payloadEncoding PayloadEncoding) ECDSAVarsig {
 	return ECDSAVarsig{
 		varsig: varsig{
-			algo:   AlgorithmECDSA,
+			disc:   DiscriminatorECDSA,
 			payEnc: payloadEncoding,
 		},
 		curve:   curve,

eddsa.go

@@ -5,8 +5,8 @@ import (
 	"fmt"
 )
 
-// AlgorithmEdDSA is the value specifying an EdDSA signature.
-const AlgorithmEdDSA = Algorithm(0xed)
+// DiscriminatorEdDSA is the value specifying an EdDSA signature.
+const DiscriminatorEdDSA = Discriminator(0xed)
 
 // EdDSACurve are values that specify which Edwards curve is used when
 // generating the signature.
@@ -49,7 +49,7 @@ type EdDSAVarsig struct {
 func NewEdDSAVarsig(curve EdDSACurve, hashAlgorithm Hash, payloadEncoding PayloadEncoding) EdDSAVarsig {
 	return EdDSAVarsig{
 		varsig: varsig{
-			algo:   AlgorithmEdDSA,
+			disc:   DiscriminatorEdDSA,
 			payEnc: payloadEncoding,
 		},
 		curve:   curve,

eddsa_test.go

@@ -29,7 +29,7 @@ func TestUCANExampleV1(t *testing.T) {
 		require.True(t, ok)
 
 		assert.Equal(t, varsig.Version1, ed25519V.Version())
-		assert.Equal(t, varsig.AlgorithmEdDSA, ed25519V.Algorithm())
+		assert.Equal(t, varsig.DiscriminatorEdDSA, ed25519V.Discriminator())
 		assert.Equal(t, varsig.CurveEd25519, ed25519V.Curve())
 		assert.Equal(t, varsig.HashSha2_512, ed25519V.Hash())
 		assert.Equal(t, varsig.PayloadEncodingDAGCBOR, ed25519V.PayloadEncoding())

error.go

@@ -16,9 +16,9 @@ var ErrUnknownHash = errors.New("unknown hash algorithm")
 // for this field may vary based on the varsig version.
 var ErrUnsupportedPayloadEncoding = errors.New("unsupported payload encoding")
 
-// ErrUnknownAlgorithm is returned when the Registry doesn't have a
+// ErrUnknownDiscriminator is returned when the Registry doesn't have a
 // parsing function for the decoded signing algorithm.
-var ErrUnknownAlgorithm = errors.New("unknown signing algorithm")
+var ErrUnknownDiscriminator = errors.New("unknown signing algorithm")
 
 // ErrUnknownEdDSACurve is returned when the decoded uvarint isn't either
 // CurveEd25519 or CurveEd448.

registry.go

@@ -22,15 +22,15 @@ type DecodeFunc func(BytesReader) (Varsig, error)
 
 // Registry contains a mapping between known signing algorithms and
 // functions that can parse varsigs for that signing algorithm.
-type Registry map[Algorithm]DecodeFunc
+type Registry map[Discriminator]DecodeFunc
 
 // DefaultRegistry provides a Registry containing the mappings for the
 // signing algorithms which have an implementation within this library.
 func DefaultRegistry() Registry {
-	return map[Algorithm]DecodeFunc{
-		AlgorithmRSA:   decodeRSA,
-		AlgorithmEdDSA: decodeEdDSA,
-		AlgorithmECDSA: decodeECDSA,
+	return map[Discriminator]DecodeFunc{
+		DiscriminatorRSA:   decodeRSA,
+		DiscriminatorEdDSA: decodeEdDSA,
+		DiscriminatorECDSA: decodeECDSA,
 	}
 }
 
@@ -41,7 +41,7 @@ func NewRegistry() Registry {
 
 // Register allows new mappings between a signing algorithm and its parsing
 // function to the Registry.
-func (rs Registry) Register(alg Algorithm, decodeFunc DecodeFunc) {
+func (rs Registry) Register(alg Discriminator, decodeFunc DecodeFunc) {
 	rs[alg] = decodeFunc
 }
 
@@ -63,7 +63,7 @@ func (rs Registry) DecodeStream(r BytesReader) (Varsig, error) {
 		return nil, fmt.Errorf("%w: expected %d, got %d", ErrBadPrefix, Prefix, pre)
 	}
 
-	vers, algo, err := rs.decodeVersAndAlgo(r)
+	vers, disc, err := rs.decodeVersAnddisc(r)
 	if err != nil {
 		return nil, err
 	}
@@ -72,15 +72,15 @@ func (rs Registry) DecodeStream(r BytesReader) (Varsig, error) {
 		return nil, fmt.Errorf("%w: %d", ErrUnsupportedVersion, vers)
 	}
 
-	decodeFunc, ok := rs[Algorithm(algo)]
+	decodeFunc, ok := rs[Discriminator(disc)]
 	if !ok {
-		return nil, fmt.Errorf("%w: %x", ErrUnknownAlgorithm, algo)
+		return nil, fmt.Errorf("%w: %x", ErrUnknownDiscriminator, disc)
 	}
 
 	return decodeFunc(r)
 }
 
-func (rs Registry) decodeVersAndAlgo(r BytesReader) (Version, Algorithm, error) {
+func (rs Registry) decodeVersAnddisc(r BytesReader) (Version, Discriminator, error) {
 	vers, err := binary.ReadUvarint(r)
 	if err != nil {
 		return Version(vers), 0, err
@@ -91,10 +91,10 @@ func (rs Registry) decodeVersAndAlgo(r BytesReader) (Version, Algorithm, error)
 	}
 
 	if vers >= 64 {
-		return 0, Algorithm(vers), nil
+		return 0, Discriminator(vers), nil
 	}
 
-	algo, err := binary.ReadUvarint(r)
+	disc, err := binary.ReadUvarint(r)
 
-	return Version(vers), Algorithm(algo), err
+	return Version(vers), Discriminator(disc), err
 }

registry_test.go

@@ -21,35 +21,35 @@ func TestRegistry_Decode(t *testing.T) {
 		vs, err := reg.DecodeStream(bytes.NewReader(data))
 		require.NoError(t, err)
 		assert.Equal(t, varsig.Version1, vs.Version())
-		assert.Equal(t, testAlgorithm1, vs.Algorithm())
+		assert.Equal(t, testDiscriminator1, vs.Discriminator())
 	})
 }
 
 const (
-	testAlgorithm0 varsig.Algorithm = 0x1000
-	testAlgorithm1 varsig.Algorithm = 0x1001
+	testDiscriminator0 varsig.Discriminator = 0x1000
+	testDiscriminator1 varsig.Discriminator = 0x1001
 )
 
 func testRegistry(t *testing.T) varsig.Registry {
 	t.Helper()
 
 	reg := varsig.NewRegistry()
-	reg.Register(testAlgorithm0, testDecodeFunc(testAlgorithm0))
-	reg.Register(testAlgorithm1, testDecodeFunc(testAlgorithm1))
+	reg.Register(testDiscriminator0, testDecodeFunc(testDiscriminator0))
+	reg.Register(testDiscriminator1, testDecodeFunc(testDiscriminator1))
 
 	return reg
 }
 
-func testDecodeFunc(algo varsig.Algorithm) varsig.DecodeFunc {
+func testDecodeFunc(disc varsig.Discriminator) varsig.DecodeFunc {
 	return func(r varsig.BytesReader) (varsig.Varsig, error) {
-		return &testVarsig{algo: algo}, nil
+		return &testVarsig{disc: disc}, nil
 	}
 }
 
 var _ varsig.Varsig = testVarsig{}
 
 type testVarsig struct {
-	algo   varsig.Algorithm
+	disc   varsig.Discriminator
 	payEnc varsig.PayloadEncoding
 }
 
@@ -57,12 +57,8 @@ func (v testVarsig) Version() varsig.Version {
 	return varsig.Version1
 }
 
-func (v testVarsig) Algorithm() varsig.Algorithm {
-	return v.algo
-}
-
-func (v testVarsig) Hash() varsig.Hash {
-	return varsig.HashUnspecified
+func (v testVarsig) Discriminator() varsig.Discriminator {
+	return v.disc
 }
 
 func (v testVarsig) PayloadEncoding() varsig.PayloadEncoding {

rsa.go

@@ -4,8 +4,8 @@ import (
 	"encoding/binary"
 )
 
-// AlgorithmRSA is the value specifying an RSA signature.
-const AlgorithmRSA = Algorithm(0x1205)
+// DiscriminatorRSA is the value specifying an RSA signature.
+const DiscriminatorRSA = Discriminator(0x1205)
 
 var _ Varsig = RSAVarsig{}
 
@@ -22,7 +22,7 @@ type RSAVarsig struct {
 func NewRSAVarsig(hashAlgorithm Hash, keyLen uint64, payloadEncoding PayloadEncoding) RSAVarsig {
 	return RSAVarsig{
 		varsig: varsig{
-			algo:   AlgorithmRSA,
+			disc:   DiscriminatorRSA,
 			payEnc: payloadEncoding,
 		},
 		hashAlg: hashAlgorithm,

rsa_test.go

@@ -29,7 +29,7 @@ func TestRSAVarsig(t *testing.T) {
 		require.True(t, ok)
 
 		require.Equal(t, varsig.Version1, rsaVs.Version())
-		require.Equal(t, varsig.AlgorithmRSA, rsaVs.Algorithm())
+		require.Equal(t, varsig.DiscriminatorRSA, rsaVs.Discriminator())
 		require.Equal(t, varsig.HashSha2_256, rsaVs.Hash())
 		require.Equal(t, varsig.PayloadEncodingDAGCBOR, rsaVs.PayloadEncoding())
 		require.Equal(t, uint64(keyLen), rsaVs.KeyLength())

varsig.go

@@ -29,11 +29,8 @@ type Varsig interface {
 	// Version returns the varsig's version field.
 	Version() Version
 
-	// Algorithm returns the algorithm used to produce the corresponding signature.
-	Algorithm() Algorithm
-
-	// Hash returns the hash used on the data before signature.
-	Hash() Hash
+	// Discriminator returns the algorithm used to produce the corresponding signature.
+	Discriminator() Discriminator
 
 	// PayloadEncoding returns the codec that was used to encode the signed data.
 	PayloadEncoding() PayloadEncoding
@@ -55,7 +52,7 @@ func DecodeStream(r BytesReader) (Varsig, error) {
 }
 
 type varsig struct {
-	algo   Algorithm
+	disc   Discriminator
 	payEnc PayloadEncoding
 }
 
@@ -64,10 +61,10 @@ func (v varsig) Version() Version {
 	return Version1
 }
 
-// Algorithm returns the algorithm used to produce the corresponding
+// Discriminator returns the algorithm used to produce the corresponding
 // signature.
-func (v varsig) Algorithm() Algorithm {
-	return v.algo
+func (v varsig) Discriminator() Discriminator {
+	return v.disc
 }
 
 // PayloadEncoding returns the codec that was used to encode the signed
@@ -84,7 +81,7 @@ func (v varsig) encode() []byte {
 
 	buf = binary.AppendUvarint(buf, Prefix)
 	buf = binary.AppendUvarint(buf, uint64(Version1))
-	buf = binary.AppendUvarint(buf, uint64(v.algo))
+	buf = binary.AppendUvarint(buf, uint64(v.disc))
 
 	return buf
 }

varsig_test.go

@@ -1,9 +1,7 @@
 package varsig_test
 
 import (
-	"encoding/base64"
 	"encoding/hex"
-	"fmt"
 	"io"
 	"testing"
 
@@ -13,39 +11,6 @@ import (
 	"github.com/ucan-wg/go-varsig"
 )
 
-func ExampleDecode() {
-	example, err := base64.RawStdEncoding.DecodeString("NAHtAe0BE3E")
-	handleErr(err)
-
-	vs, err := varsig.Decode(example)
-	handleErr(err)
-
-	fmt.Printf("%T\n", vs)
-	fmt.Printf("Algorithm: %d\n", vs.Algorithm())
-	fmt.Printf("Hash: %d\n", vs.Hash())
-	fmt.Printf("PayloadEncoding: %d\n", vs.PayloadEncoding())
-
-	// Output:
-	// varsig.EdDSAVarsig
-	// Algorithm: 237
-	// Hash: 19
-	// PayloadEncoding: 3
-}
-
-func ExampleEncode() {
-	edDSAVarsig := varsig.NewEdDSAVarsig(
-		varsig.CurveEd25519,
-		varsig.HashSha2_512,
-		varsig.PayloadEncodingDAGCBOR,
-	)
-
-	b64 := base64.RawStdEncoding.EncodeToString(edDSAVarsig.Encode())
-	fmt.Print(b64)
-
-	// Output:
-	// NAHtAe0BE3E
-}
-
 func TestDecode(t *testing.T) {
 	t.Parallel()
 
@@ -100,7 +65,7 @@ func TestDecode(t *testing.T) {
 		require.NoError(t, err)
 
 		vs, err := varsig.Decode(data)
-		require.ErrorIs(t, err, varsig.ErrUnknownAlgorithm)
+		require.ErrorIs(t, err, varsig.ErrUnknownDiscriminator)
 		assert.Nil(t, vs)
 	})
 
@@ -147,9 +112,3 @@ func TestDecode(t *testing.T) {
 		assert.Nil(t, vs)
 	})
 }
-
-func handleErr(err error) {
-	if err != nil {
-		panic(err)
-	}
-}