Documentation
¶
Overview ¶
Package capabilityhttp integrates verified signed-URL grants with net/http without hiding application authorization or bounded-use consumption.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GrantFromContext ¶
func GrantFromContext(ctx context.Context) (capability.Grant, bool)
GrantFromContext returns the verified grant carried by Middleware.
func SignRequest ¶
func SignRequest( ctx context.Context, request *http.Request, payload capability.Payload, profile capability.URLProfile, signer capability.Signer, limits capability.Limits, bodyDigest []byte, ) error
SignRequest signs req.URL and mutates it only after complete successful issuance.
Example ¶
now := time.Date(2026, 9, 9, 12, 0, 0, 0, time.UTC)
signer, _ := capability.NewHMACSHA256Signer(
"current", []byte("0123456789abcdef0123456789abcdef"),
)
request, _ := http.NewRequest(http.MethodGet, "https://files.example/report/42", nil)
profile := capability.URLProfile{
Name: "download-v1", SignatureParameter: "cap",
AllowedSchemes: []string{"https"}, AllowedAuthorities: []string{"files.example"},
}
payload := capability.Payload{
Version: 1, Issuer: "https://issuer.example", Audiences: []string{"download-service"},
Bearer: true, IssuedAt: now, NotBefore: now, ExpiresAt: now.Add(time.Minute), ID: "cap-42",
}
err := capabilityhttp.SignRequest(
context.Background(), request, payload, profile, signer, capability.DefaultLimits(), nil,
)
fmt.Println(err == nil, strings.HasPrefix(request.URL.RawQuery, "cap="))
Output: true true
Types ¶
type BodyDigest ¶
BodyDigest obtains an already computed SHA-256 digest. It must not consume a request body unless it also restores it for the application.
type ErrorHandler ¶
type ErrorHandler func(http.ResponseWriter, *http.Request, error)
ErrorHandler writes a secret-safe verification failure response.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier verifies request URLs and attaches authenticated grants to context.
func NewVerifier ¶
func NewVerifier(options VerifierOptions) (*Verifier, error)
NewVerifier validates an HTTP integration. Origin is trusted static external configuration for absolute profiles; request forwarding headers are ignored.
func (*Verifier) Middleware ¶
Middleware verifies and carries a Grant. The next handler remains responsible for Grant.Authorize, Grant.Consume, and the protected side effect ordering.
func (*Verifier) VerifyRequest ¶
VerifyRequest verifies a request but does not authorize or consume its grant.
type VerifierOptions ¶
type VerifierOptions struct {
// Issuer is the required trusted namespace, never inferred from the request.
Issuer string
Profile capability.URLProfile
Resolver capability.Resolver
Origin string
Clock Clock
Skew time.Duration
Limits capability.Limits
Revocations capability.RevocationChecker
BodyDigest BodyDigest
ErrorHandler ErrorHandler
}
VerifierOptions configures signed-URL verification for one immutable profile.
Source Files