Documentation
¶
Overview ¶
Package capabilityhttp integrates verified signed-URL grants with net/http without hiding application authorization or bounded-use consumption. Start with NewVerifier and trusted static Origin/Issuer; SignRequest only mutates an explicitly supplied outgoing URL. It owns no server/client/body lifecycle or worker. Profiles and callbacks stay borrowed and immutable; shared use requires cooperative concurrent-safe collaborators. The local signed-URL policy is DEC-006/007/011, not HTTP Message Signatures or automatic effects.
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 middleware Grant or zero/false for nil/absent context. Presence is authentication attribution, not authorization or use count.
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 request.URL and replaces it only after successful issuance. Caller owns exclusive URL mutation and supplies already computed body digest. No body read, HTTP send, header rewriting or rollback of signer effects occurs.
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. Bound untrusted pre-authentication work, honor request context and support concurrent calls. Returned digest is borrowed for that call; panics are not contained.
type Clock ¶
type Clock interface {
// Now supplies trusted wall time, concurrently and promptly without reading
// untrusted request fields.
Now() time.Time
}
Clock supplies request-time wall clock values.
type ErrorHandler ¶
type ErrorHandler func(http.ResponseWriter, *http.Request, error)
ErrorHandler owns synchronous failure rendering/redaction. It may run concurrently; bound work and never expose tokens or underlying diagnostics. Handler panics are not contained; nil configuration selects fixed 401 text.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier verifies request URLs and carries grants. Construct with NewVerifier; zero is unusable. Shared use requires immutable profile slices and safe clock/resolver/digest/error callbacks; they can block or panic synchronously.
func NewVerifier ¶
func NewVerifier(options VerifierOptions) (*Verifier, error)
NewVerifier validates an HTTP integration. Origin is trusted static external configuration for absolute profiles; request host/forwarding headers are ignored. Profile slices and callbacks stay borrowed for lifetime, not defensively cloned. Failure returns nil; nil interfaces reject, typed nil is not detected.
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. Nil next produces a fixed 500; verification failure invokes ErrorHandler. Custom handler redaction/panics and downstream effects remain caller-owned. It creates no worker and carries the same grant visible through caphttp.
func (*Verifier) VerifyRequest ¶
VerifyRequest verifies a request but does not authorize or consume its grant. Nil request/URL refuses. BodyDigest runs before authentication; the caller must bound untrusted reads and restore bytes for later handlers. Digest errors are sanitized to ErrURLBinding/context categories; no panic or forced timeout boundary is added. Only selected static origin plus RequestURI is trusted.
type VerifierOptions ¶
type VerifierOptions struct {
// Issuer is the required trusted namespace, never inferred from the request.
Issuer string
// Profile is validated by value, but its slice storage remains borrowed and immutable
// for verifier lifetime.
Profile capability.URLProfile
// Resolver is mandatory borrowed trusted issuer/key policy; shared use must be
// concurrency-safe.
Resolver capability.Resolver
// Origin is trusted static scheme/authority required for absolute profiles, never
// request Host or forwarding data.
Origin string
// Clock is mandatory borrowed safe wall clock; callbacks must return promptly and
// support concurrent use.
Clock Clock
// Skew is nonnegative payload time tolerance, not an HTTP deadline.
Skew time.Duration
// Limits is explicit positive parser policy, copied by value.
Limits capability.Limits
// Revocations is optional borrowed post-authentication policy; nil disables revocation.
Revocations capability.RevocationChecker
// BodyDigest must be present exactly when required; bound pre-authentication work and
// restore consumed bodies.
BodyDigest BodyDigest
// ErrorHandler is optional synchronous failure reporting; nil selects fixed 401 text,
// custom handlers own redaction.
ErrorHandler ErrorHandler
}
VerifierOptions configures signed-URL verification for one immutable profile.
Source Files