Add crypto.Signer option to CommitOptions.

[wlynch]

This change adds a new crypto.Signer option to CommitOptions as an alternative to SignKey to allow alternative commit signers to be used. This change does not add other signing or verification methods (e.g. ssh, x509, gitsign), but gives callers the ability to start adding their own signing implementations.

This differs from #705 by using the stdlib crypto.Signer interface instead of defining a new ObjectSigner interface. We could go with that approach if we want, but using a []byte based approach means that Signer implementations do not need to be aware of how commit encoding works (which is closer to git's sign_buffer implementation).

Part of #400

cc @hiddeco

[hiddeco]

What would the verification counterpart of this look like? As we also do have a built-in functionality for this, which would need to be updated at some point.

[hiddeco]

(I very much like this approach by the way, just looking at the full picture).

[pjbgf]

+1 on the approach.

We just need to also agree on the API for the verification so that the user experience from an API perspective is coherent.

[wlynch]

Verification ends up being a different beast, mostly because what you want to get out of verification differs wildly based on the type of signing that was done.

The main thing I want to focus on is making sure that signers and verifiers don't need to be aware of how commit marshaling needs to be done - ideally they should only need to work on []bytes and whatever impl specific parameters they need to operate. There is no standard lib verify interface, so we have to define our own.

If you only care about whether a signature is valid, then a simple interface like this would be sufficient:

type SignatureVerifier interface {
  Verify(message, signature []byte, opts ...VerifyOption) error
}

(This is similar to Sigstore's Verifier interface)

But often callers want to inspect data about the signer after it's been verified. Today for GPG signing, we return the Entity, for x509 you probably want the Certificate, for gitsign you probably want the Certificate + Rekor entry. I don't think there's an easy way to try and abstract these return types away unless you use generics or any:

type SignatureVerifier[T any] interface {
	Verify(message, body []byte, opts ...VerifyOption) (T, error)
}

And if you're trying to verify multiple signature types at once (which notably git itself doesn't really support well), I think you're mostly stuck with any + type assertion anyway.

I'm also okay with something like Entity proposed in #705 as well, but we'd have to be careful about what fields we try to generalize across signing types, and most applications would likely end up falling back to type assertion anyway. 🤷

---

From there, I think we can follow what #705 does with ObjectVerifier - same as before, we can either return a generic or Entity. The only difference is I think ObjectVerifier should be a struct to encapsulate the commit marshaling:

// ObjectVerifier is capable of verifying the signature of a VerifiableObject.
type ObjectVerifier struct {
	verifier SignatureVerifier
}

func (v *ObjectVerifier) Verify(o VerifiableObject) (Entity, error) {
	// Extract signature.
	signature := []byte{t.PGPSignature}

	encoded := &plumbing.MemoryObject{}
	// Encode tag components, excluding signature and get a reader object.
	if err := t.EncodeWithoutSignature(encoded); err != nil {
		return nil, err
	}
	er, err := encoded.Reader()
	if err != nil {
		return nil, err
	}
	b, err := io.ReadAll(er)
	if err != nil {
		return nil, err
	}

	return v.verifier(b, signature)
}

[hiddeco]

LGTM, thanks @wlynch 🙇

[wlynch]

Updated commit message to match the expected format!

[pjbgf]

@wlynch thanks for working on this. 🙇