Add select-by-tag helpers for signature labels

[yaronf]

Summary

WIMSE HTTP-Sig (draft-ietf-wimse-http-signature) requires recipients to locate the protocol signature by the tag signature parameter, not by the RFC 9421 label. When multiple signatures are present, the label is non-semantic and may be changed by intermediaries.

Today callers must stitch this together manually:

1. RequestSignatureNames / ResponseSignatureNames
2. RequestDetails / ResponseDetails per label to read MessageDetails.Tag
3. enforce uniqueness (zero or >1 match → reject)
4. VerifyRequest / VerifyResponse on the chosen label

Example from wimse-s2s-doc:

func findSignatureByTag(names []string, detailsFn func(string) (*httpsign.MessageDetails, error), wantTag string) (string, error) {
    var found []string
    for _, name := range names {
        details, err := detailsFn(name)
        if err != nil {
            return "", fmt.Errorf("details for %q: %w", name, err)
        }
        if details.Tag != nil && *details.Tag == wantTag {
            found = append(found, name)
        }
    }
    switch len(found) {
    case 0:
        return "", fmt.Errorf("no signature with tag %q", wantTag)
    case 1:
        return found[0], nil
    default:
        return "", fmt.Errorf("multiple signatures with tag %q", wantTag)
    }
}

Proposal

Add library helpers, e.g.:

// Strict: returns error if zero or more than one label matches.
func SelectRequestSignatureByTag(req *http.Request, tag string) (label string, details *MessageDetails, err error)
func SelectResponseSignatureByTag(res *http.Response, tag string) (label string, details *MessageDetails, err error)

// Lenient: returns all matching labels (possibly empty slice).
func RequestSignatureLabelsByTag(req *http.Request, tag string) ([]string, error)
func ResponseSignatureLabelsByTag(res *http.Response, tag string) ([]string, error)

Notes:

• Selection uses parsed Signature-Input only; it does not verify the signature.
• Distinct sentinel errors for "not found" vs "ambiguous" would help callers.
• Optional follow-up: VerifyRequestByTag / VerifyResponseByTag combining select + verify.

Motivation

This pattern is required by WIMSE and likely other RFC 9421 profiles that use tag. Centralizing it avoids every application reimplementing the same loop and error handling.