Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ This file provides repository-specific guidance for AI coding agents working on
- Validate before lossy conversion: preserve parameter presence, types, and values until the relevant checks are complete.
- Preserve protocol-level type distinctions across parsing, serialization, public APIs, and comparisons. When changing supported types, test round trips and assess compatibility implications.
- Review untrusted-input paths for possible panics, including unchecked type assertions, nil dereferences, and dependency behavior. Malformed protocol input should produce controlled errors.
- Respect the API contracts for Structured Fields component identifiers and any supported simplified configuration syntax.
- Public component identifier strings in configuration and results use serialized Structured Fields String Items.
- Never relax signature, component, timestamp, nonce, algorithm, or key validation merely to satisfy tests. Assess security and compatibility implications explicitly.

## Test design
Expand Down
42 changes: 16 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,6 @@ For API details and option semantics, see the [Go reference](https://pkg.go.dev/

## Usage

> [!NOTE]
> Component identifiers are represented as [Structured Fields Items](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.5), with quoted component names (for example, `"@method"` or `"content-digest";req`). For convenience, configuration options such as `WithComponents` also accept a simplified form that omits the quotes around the component name. Both forms are equivalent:
>
> ```go
> httpsig.WithComponents(`"@method"`, `"content-digest";req`) // Structured Fields form
> httpsig.WithComponents("@method", "content-digest;req") // simplified form
> ```
>
> When parsing an `Accept-Signature` header, `httpsig` returns the serialized Structured Fields form in `SignatureRequest.Components`. These values can be passed directly to `WithComponents`.

### Standalone Signing and Verification

The following snippets show two independent flows: signing an outgoing request and verifying a received response. They assume application-provided keys and other values; routine error handling is abbreviated.
Expand All @@ -45,7 +35,7 @@ signer, err := httpsig.NewSigner(
// duration for which the signature should be valid
httpsig.WithTTL(5 * time.Second),
// which components should be protected by a signature
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
httpsig.WithComponents(`"@authority"`, `"@method"`, `"x-my-fancy-header"`),
// a tag for your specific application
httpsig.WithTag("myapp"),
// custom parameter
Expand Down Expand Up @@ -90,7 +80,7 @@ verifier, err := httpsig.NewVerifier(
keyResolver,
// specify the required options
// which response components are expected to be protected
httpsig.WithComponents("@status", "content-type"),
httpsig.WithComponents(`"@status"`, `"content-type"`),
// validity time skew
httpsig.WithValidityTolerance(5 * time.Second),
// how old a signature is allowed to be
Expand Down Expand Up @@ -122,7 +112,7 @@ verifier, err := httpsig.NewVerifier(
// tag of the signature
"myapp",
// which components are expected to be protected by a signature
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
httpsig.WithComponents(`"@authority"`, `"@method"`, `"x-my-fancy-header"`),
// validity time skew
httpsig.WithValidityTolerance(5 * time.Second),
// how old a signature is allowed to be
Expand Down Expand Up @@ -204,7 +194,7 @@ builder, err := httpsig.NewAcceptSignature(
// request the label and covered components
httpsig.WithLabel("bar"),
// specify which components should be covered by the signature
httpsig.WithComponents("@status", "content-digest;req", "content-digest"),
httpsig.WithComponents(`"@status"`, `"content-digest";req`, `"content-digest"`),
// specify your content digest algorithm references
httpsig.WithContentDigestAlgorithmPreferences(httpsig.AlgorithmPreference{Algorithm: httpsig.Sha256, Preference: 2}),
// specify which tag the server should use
Expand Down Expand Up @@ -288,7 +278,7 @@ verifier, err := httpsig.NewVerifier(
// tag of the signature
"myapp",
// which components are expected to be protected by a signature
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
httpsig.WithComponents(`"@authority"`, `"@method"`, `"x-my-fancy-header"`),
// validity time skew
httpsig.WithValidityTolerance(5 * time.Second),
// how old a signature is allowed to be
Expand Down Expand Up @@ -370,7 +360,7 @@ signer, err := httpsig.NewSigner(
},
httpsig.WithKeyID("demo-ml-dsa-44"),
httpsig.WithAlg(),
httpsig.WithComponents("@method", "@path"),
httpsig.WithComponents(`"@method"`, `"@path"`),
)
// error handling

Expand All @@ -387,7 +377,7 @@ verifier, err := httpsig.NewVerifier(
Algorithm: "ml-dsa-44",
},
httpsig.WithValidateAllSignatures(),
httpsig.WithComponents("@method", "@path"),
httpsig.WithComponents(`"@method"`, `"@path"`),
)
// error handling

Expand Down Expand Up @@ -438,7 +428,7 @@ signer, err := httpsig.NewSigner(
Algorithm: httpsig.EcdsaP256Sha256,
},
httpsig.WithKeyID(keyID),
httpsig.WithComponents("@method", "@path"),
httpsig.WithComponents(`"@method"`, `"@path"`),
)
// error handling

Expand All @@ -459,7 +449,7 @@ The [WIMSE HTTP Signatures draft](https://datatracker.ietf.org/doc/html/draft-ie
signer, err := httpsig.NewSigner(
httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519},
httpsig.WithTag("wimse-workload-to-workload"),
httpsig.WithComponents("@method", "@path", "@query", "workload-identity-token"),
httpsig.WithComponents(`"@method"`, `"@path"`, `"@query"`, `"workload-identity-token"`),
)

req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
Expand All @@ -470,7 +460,7 @@ req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
// Recipient
verifier, err := httpsig.NewVerifier(witKeyResolver,
httpsig.WithRequiredTag("wimse-workload-to-workload",
httpsig.WithComponents("@method", "@path", "@query", "workload-identity-token"),
httpsig.WithComponents(`"@method"`, `"@path"`, `"@query"`, `"workload-identity-token"`),
httpsig.WithRequiredParameters(httpsig.Nonce),
httpsig.WithForbiddenParameters(httpsig.KeyID, httpsig.Alg),
httpsig.WithParameter("wimse-aud", expectedAudience),
Expand All @@ -494,15 +484,15 @@ signer, err := httpsig.NewSigner(
httpsig.WithLabel("sig1"),
httpsig.WithTag("web-bot-auth"),
httpsig.WithKeyID(jwkThumbprint),
httpsig.WithComponents("@authority", `signature-agent;key="sig1"`),
httpsig.WithComponents(`"@authority"`, `"signature-agent";key="sig1"`),
)

req.Header, err = signer.Sign(httpsig.MessageFromRequest(req))

// Recipient: resolve the covered Signature-Agent member dynamically.
verifier, err := httpsig.NewVerifier(webBotKeyResolver,
httpsig.WithRequiredTag("web-bot-auth",
httpsig.WithComponents("@authority", `signature-agent;key="sig1"`),
httpsig.WithComponents(`"@authority"`, `"signature-agent";key="sig1"`),
httpsig.WithRequiredParameters(httpsig.KeyID),
),
)
Expand All @@ -523,14 +513,14 @@ signer, err := httpsig.NewSigner(
httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519},
httpsig.WithLabel("sig"),
httpsig.WithTTL(0),
httpsig.WithComponents("@method", "@authority", "@path", "signature-key"),
httpsig.WithComponents(`"@method"`, `"@authority"`, `"@path"`, `"signature-key"`),
)
req.Header, err = signer.Sign(httpsig.MessageFromRequest(req))

// Resource server
verifier, err := httpsig.NewVerifier(aauthKeyResolver,
httpsig.WithValidateAllSignatures(),
httpsig.WithComponents("@method", "@authority", "@path", "signature-key"),
httpsig.WithComponents(`"@method"`, `"@authority"`, `"@path"`, `"signature-key"`),
httpsig.WithExpiresTimestamp(false),
httpsig.WithMaxAge(time.Minute),
)
Expand All @@ -549,7 +539,7 @@ signer, err := httpsig.NewSigner(
httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519},
httpsig.WithTag("httpsig-oauth"),
httpsig.WithTTL(0),
httpsig.WithComponents("@method", "@target-uri", "authorization"),
httpsig.WithComponents(`"@method"`, `"@target-uri"`, `"authorization"`),
)

req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
Expand All @@ -559,7 +549,7 @@ req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
// Resource server
verifier, err := httpsig.NewVerifier(tokenBoundKeyResolver,
httpsig.WithRequiredTag("httpsig-oauth",
httpsig.WithComponents("@method", "@target-uri", "authorization"),
httpsig.WithComponents(`"@method"`, `"@target-uri"`, `"authorization"`),
httpsig.WithExpiresTimestamp(false),
httpsig.WithRequiredParameters(httpsig.Nonce),
httpsig.WithForbiddenParameters(httpsig.KeyID, httpsig.Alg, "pub"),
Expand Down
14 changes: 7 additions & 7 deletions accept_signature_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ func TestNewAcceptedSignature(t *testing.T) {
WithKeyID("test"),
WithNonceGetter(&NonceGetterMock{}),
WithLabel("foo"),
WithComponents("@status", "content-digest;req"),
WithComponents(`"@status"`, `"content-digest";req`),
WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 10}),
WithTag("bar"),
WithCreatedTimestamp(false),
Expand Down Expand Up @@ -86,7 +86,7 @@ func TestNewAcceptedSignature(t *testing.T) {
},
"option raises error": {
opts: []AcceptSignatureOption{
WithComponents("@foo"),
WithComponents(`"@foo"`),
},
assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) {
t.Helper()
Expand Down Expand Up @@ -277,7 +277,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
opts: []AcceptSignatureOption{
WithSignatureAlgorithm(EcdsaP256Sha256),
WithKeyID("test"),
WithComponents("@status", "x-foo-bar;req", "@method"),
WithComponents(`"@status"`, `"x-foo-bar";req`, `"@method"`),
WithLabel("foo"),
WithTag("bar"),
WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })),
Expand All @@ -296,8 +296,8 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
},
"Want-Content-Digest is omitted after overriding covered components": {
opts: []AcceptSignatureOption{
WithComponents("@status", "content-digest"),
WithComponents("@method"),
WithComponents(`"@status"`, `"content-digest"`),
WithComponents(`"@method"`),
},
assert: func(t *testing.T, err error, hdr http.Header) {
t.Helper()
Expand All @@ -311,7 +311,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
opts: []AcceptSignatureOption{
WithSignatureAlgorithm(EcdsaP256Sha256),
WithKeyID("test"),
WithComponents("@status", "content-digest", "@method"),
WithComponents(`"@status"`, `"content-digest"`, `"@method"`),
WithLabel("foo"),
WithTag("bar"),
WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })),
Expand All @@ -334,7 +334,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
opts: []AcceptSignatureOption{
WithSignatureAlgorithm(EcdsaP256Sha256),
WithKeyID("test"),
WithComponents("@status", "content-digest", "@method"),
WithComponents(`"@status"`, `"content-digest"`, `"@method"`),
WithLabel("foo"),
WithTag("bar"),
WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })),
Expand Down
23 changes: 1 addition & 22 deletions component_identifier.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,6 @@ import (
"github.com/dunglas/httpsfv"
)

func quoteIdentifierName(input string) string {
// nothing to do if already quoted
if strings.HasPrefix(input, `"`) {
return input
}

// try to split the structured field
parts := strings.Split(input, ";")
name, rest := parts[0], parts[1:]

// always quote the name
identifier := "\"" + name + "\""

if len(rest) == 0 {
return identifier
}

// just add the rest
return identifier + ";" + strings.Join(rest, ";")
}

type componentIdentifier struct {
httpsfv.Item

Expand All @@ -39,7 +18,7 @@ func toComponentIdentifiers(identifiers []string) ([]*componentIdentifier, error
cis := make([]*componentIdentifier, 0, len(identifiers))

for _, identifier := range identifiers {
item, err := httpsfv.UnmarshalItem([]string{quoteIdentifierName(identifier)})
item, err := httpsfv.UnmarshalItem([]string{identifier})
if err != nil {
return nil, fmt.Errorf("%w: %s: %w", ErrInvalidComponentIdentifier, identifiers, err)
}
Expand Down
Loading
Loading