Skip to content

Commit 6e68062

Browse files
authored
refactor!: Component identifier representation standardized (#204)
1 parent 000f844 commit 6e68062

16 files changed

Lines changed: 278 additions & 267 deletions

‎AGENTS.md‎

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

3333
## Test design

‎README.md‎

Lines changed: 16 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,6 @@ For API details and option semantics, see the [Go reference](https://pkg.go.dev/
1818

1919
## Usage
2020

21-
> [!NOTE]
22-
> 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:
23-
>
24-
> ```go
25-
> httpsig.WithComponents(`"@method"`, `"content-digest";req`) // Structured Fields form
26-
> httpsig.WithComponents("@method", "content-digest;req") // simplified form
27-
> ```
28-
>
29-
> When parsing an `Accept-Signature` header, `httpsig` returns the serialized Structured Fields form in `SignatureRequest.Components`. These values can be passed directly to `WithComponents`.
30-
3121
### Standalone Signing and Verification
3222

3323
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.
@@ -45,7 +35,7 @@ signer, err := httpsig.NewSigner(
4535
// duration for which the signature should be valid
4636
httpsig.WithTTL(5 * time.Second),
4737
// which components should be protected by a signature
48-
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
38+
httpsig.WithComponents(`"@authority"`, `"@method"`, `"x-my-fancy-header"`),
4939
// a tag for your specific application
5040
httpsig.WithTag("myapp"),
5141
// custom parameter
@@ -90,7 +80,7 @@ verifier, err := httpsig.NewVerifier(
9080
keyResolver,
9181
// specify the required options
9282
// which response components are expected to be protected
93-
httpsig.WithComponents("@status", "content-type"),
83+
httpsig.WithComponents(`"@status"`, `"content-type"`),
9484
// validity time skew
9585
httpsig.WithValidityTolerance(5 * time.Second),
9686
// how old a signature is allowed to be
@@ -122,7 +112,7 @@ verifier, err := httpsig.NewVerifier(
122112
// tag of the signature
123113
"myapp",
124114
// which components are expected to be protected by a signature
125-
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
115+
httpsig.WithComponents(`"@authority"`, `"@method"`, `"x-my-fancy-header"`),
126116
// validity time skew
127117
httpsig.WithValidityTolerance(5 * time.Second),
128118
// how old a signature is allowed to be
@@ -204,7 +194,7 @@ builder, err := httpsig.NewAcceptSignature(
204194
// request the label and covered components
205195
httpsig.WithLabel("bar"),
206196
// specify which components should be covered by the signature
207-
httpsig.WithComponents("@status", "content-digest;req", "content-digest"),
197+
httpsig.WithComponents(`"@status"`, `"content-digest";req`, `"content-digest"`),
208198
// specify your content digest algorithm references
209199
httpsig.WithContentDigestAlgorithmPreferences(httpsig.AlgorithmPreference{Algorithm: httpsig.Sha256, Preference: 2}),
210200
// specify which tag the server should use
@@ -288,7 +278,7 @@ verifier, err := httpsig.NewVerifier(
288278
// tag of the signature
289279
"myapp",
290280
// which components are expected to be protected by a signature
291-
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
281+
httpsig.WithComponents(`"@authority"`, `"@method"`, `"x-my-fancy-header"`),
292282
// validity time skew
293283
httpsig.WithValidityTolerance(5 * time.Second),
294284
// how old a signature is allowed to be
@@ -370,7 +360,7 @@ signer, err := httpsig.NewSigner(
370360
},
371361
httpsig.WithKeyID("demo-ml-dsa-44"),
372362
httpsig.WithAlg(),
373-
httpsig.WithComponents("@method", "@path"),
363+
httpsig.WithComponents(`"@method"`, `"@path"`),
374364
)
375365
// error handling
376366

@@ -387,7 +377,7 @@ verifier, err := httpsig.NewVerifier(
387377
Algorithm: "ml-dsa-44",
388378
},
389379
httpsig.WithValidateAllSignatures(),
390-
httpsig.WithComponents("@method", "@path"),
380+
httpsig.WithComponents(`"@method"`, `"@path"`),
391381
)
392382
// error handling
393383

@@ -438,7 +428,7 @@ signer, err := httpsig.NewSigner(
438428
Algorithm: httpsig.EcdsaP256Sha256,
439429
},
440430
httpsig.WithKeyID(keyID),
441-
httpsig.WithComponents("@method", "@path"),
431+
httpsig.WithComponents(`"@method"`, `"@path"`),
442432
)
443433
// error handling
444434

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

465455
req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
@@ -470,7 +460,7 @@ req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
470460
// Recipient
471461
verifier, err := httpsig.NewVerifier(witKeyResolver,
472462
httpsig.WithRequiredTag("wimse-workload-to-workload",
473-
httpsig.WithComponents("@method", "@path", "@query", "workload-identity-token"),
463+
httpsig.WithComponents(`"@method"`, `"@path"`, `"@query"`, `"workload-identity-token"`),
474464
httpsig.WithRequiredParameters(httpsig.Nonce),
475465
httpsig.WithForbiddenParameters(httpsig.KeyID, httpsig.Alg),
476466
httpsig.WithParameter("wimse-aud", expectedAudience),
@@ -494,15 +484,15 @@ signer, err := httpsig.NewSigner(
494484
httpsig.WithLabel("sig1"),
495485
httpsig.WithTag("web-bot-auth"),
496486
httpsig.WithKeyID(jwkThumbprint),
497-
httpsig.WithComponents("@authority", `signature-agent;key="sig1"`),
487+
httpsig.WithComponents(`"@authority"`, `"signature-agent";key="sig1"`),
498488
)
499489

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

502492
// Recipient: resolve the covered Signature-Agent member dynamically.
503493
verifier, err := httpsig.NewVerifier(webBotKeyResolver,
504494
httpsig.WithRequiredTag("web-bot-auth",
505-
httpsig.WithComponents("@authority", `signature-agent;key="sig1"`),
495+
httpsig.WithComponents(`"@authority"`, `"signature-agent";key="sig1"`),
506496
httpsig.WithRequiredParameters(httpsig.KeyID),
507497
),
508498
)
@@ -523,14 +513,14 @@ signer, err := httpsig.NewSigner(
523513
httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519},
524514
httpsig.WithLabel("sig"),
525515
httpsig.WithTTL(0),
526-
httpsig.WithComponents("@method", "@authority", "@path", "signature-key"),
516+
httpsig.WithComponents(`"@method"`, `"@authority"`, `"@path"`, `"signature-key"`),
527517
)
528518
req.Header, err = signer.Sign(httpsig.MessageFromRequest(req))
529519

530520
// Resource server
531521
verifier, err := httpsig.NewVerifier(aauthKeyResolver,
532522
httpsig.WithValidateAllSignatures(),
533-
httpsig.WithComponents("@method", "@authority", "@path", "signature-key"),
523+
httpsig.WithComponents(`"@method"`, `"@authority"`, `"@path"`, `"signature-key"`),
534524
httpsig.WithExpiresTimestamp(false),
535525
httpsig.WithMaxAge(time.Minute),
536526
)
@@ -549,7 +539,7 @@ signer, err := httpsig.NewSigner(
549539
httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519},
550540
httpsig.WithTag("httpsig-oauth"),
551541
httpsig.WithTTL(0),
552-
httpsig.WithComponents("@method", "@target-uri", "authorization"),
542+
httpsig.WithComponents(`"@method"`, `"@target-uri"`, `"authorization"`),
553543
)
554544

555545
req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
@@ -559,7 +549,7 @@ req.Header, err = signer.Sign(httpsig.MessageFromRequest(req),
559549
// Resource server
560550
verifier, err := httpsig.NewVerifier(tokenBoundKeyResolver,
561551
httpsig.WithRequiredTag("httpsig-oauth",
562-
httpsig.WithComponents("@method", "@target-uri", "authorization"),
552+
httpsig.WithComponents(`"@method"`, `"@target-uri"`, `"authorization"`),
563553
httpsig.WithExpiresTimestamp(false),
564554
httpsig.WithRequiredParameters(httpsig.Nonce),
565555
httpsig.WithForbiddenParameters(httpsig.KeyID, httpsig.Alg, "pub"),

‎accept_signature_test.go‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ func TestNewAcceptedSignature(t *testing.T) {
4545
WithKeyID("test"),
4646
WithNonceGetter(&NonceGetterMock{}),
4747
WithLabel("foo"),
48-
WithComponents("@status", "content-digest;req"),
48+
WithComponents(`"@status"`, `"content-digest";req`),
4949
WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 10}),
5050
WithTag("bar"),
5151
WithCreatedTimestamp(false),
@@ -86,7 +86,7 @@ func TestNewAcceptedSignature(t *testing.T) {
8686
},
8787
"option raises error": {
8888
opts: []AcceptSignatureOption{
89-
WithComponents("@foo"),
89+
WithComponents(`"@foo"`),
9090
},
9191
assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) {
9292
t.Helper()
@@ -277,7 +277,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
277277
opts: []AcceptSignatureOption{
278278
WithSignatureAlgorithm(EcdsaP256Sha256),
279279
WithKeyID("test"),
280-
WithComponents("@status", "x-foo-bar;req", "@method"),
280+
WithComponents(`"@status"`, `"x-foo-bar";req`, `"@method"`),
281281
WithLabel("foo"),
282282
WithTag("bar"),
283283
WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })),
@@ -296,8 +296,8 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
296296
},
297297
"Want-Content-Digest is omitted after overriding covered components": {
298298
opts: []AcceptSignatureOption{
299-
WithComponents("@status", "content-digest"),
300-
WithComponents("@method"),
299+
WithComponents(`"@status"`, `"content-digest"`),
300+
WithComponents(`"@method"`),
301301
},
302302
assert: func(t *testing.T, err error, hdr http.Header) {
303303
t.Helper()
@@ -311,7 +311,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
311311
opts: []AcceptSignatureOption{
312312
WithSignatureAlgorithm(EcdsaP256Sha256),
313313
WithKeyID("test"),
314-
WithComponents("@status", "content-digest", "@method"),
314+
WithComponents(`"@status"`, `"content-digest"`, `"@method"`),
315315
WithLabel("foo"),
316316
WithTag("bar"),
317317
WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })),
@@ -334,7 +334,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) {
334334
opts: []AcceptSignatureOption{
335335
WithSignatureAlgorithm(EcdsaP256Sha256),
336336
WithKeyID("test"),
337-
WithComponents("@status", "content-digest", "@method"),
337+
WithComponents(`"@status"`, `"content-digest"`, `"@method"`),
338338
WithLabel("foo"),
339339
WithTag("bar"),
340340
WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })),

‎component_identifier.go‎

Lines changed: 1 addition & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,6 @@ import (
88
"github.com/dunglas/httpsfv"
99
)
1010

11-
func quoteIdentifierName(input string) string {
12-
// nothing to do if already quoted
13-
if strings.HasPrefix(input, `"`) {
14-
return input
15-
}
16-
17-
// try to split the structured field
18-
parts := strings.Split(input, ";")
19-
name, rest := parts[0], parts[1:]
20-
21-
// always quote the name
22-
identifier := "\"" + name + "\""
23-
24-
if len(rest) == 0 {
25-
return identifier
26-
}
27-
28-
// just add the rest
29-
return identifier + ";" + strings.Join(rest, ";")
30-
}
31-
3211
type componentIdentifier struct {
3312
httpsfv.Item
3413

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

4120
for _, identifier := range identifiers {
42-
item, err := httpsfv.UnmarshalItem([]string{quoteIdentifierName(identifier)})
21+
item, err := httpsfv.UnmarshalItem([]string{identifier})
4322
if err != nil {
4423
return nil, fmt.Errorf("%w: %s: %w", ErrInvalidComponentIdentifier, identifiers, err)
4524
}

0 commit comments

Comments
 (0)