Documentation
¶
Overview ¶
Package capability issues and verifies narrowly scoped, tamper-evident grants. Verification authenticates encoded authority; applications must separately authorize each attempted use against the returned Grant.
Index ¶
- Variables
- func CanonicalPayload(payload Payload, limits Limits) ([]byte, error)
- func Issue(ctx context.Context, payload Payload, signer Signer, limits Limits) (string, error)
- func SignURL(ctx context.Context, payload Payload, request URLRequest, profile URLProfile, ...) (string, error)
- type Algorithm
- type BoundedResolver
- type BoundedResolverOptions
- type Consumption
- type ConsumptionResult
- type ConsumptionStore
- type ConsumptionStoreFunc
- type Grant
- type Header
- type Key
- type KeySet
- type Limits
- type Parsed
- type Payload
- type ResolvedKey
- type Resolver
- type ResolverFunc
- type RevocationChecker
- type RevocationCheckerFunc
- type RevocationQuery
- type Signer
- type URLProfile
- type URLRequest
- type Use
- type Verifier
- type VerifyOptions
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCapacity reports refusal before state insertion or consumption. Trusted // adapters must only return this classification when no use was committed. ErrCapacity = errors.New("capability: state capacity reached") // ErrInvalidConfiguration reports an unsafe or incomplete caller policy. ErrInvalidConfiguration = errors.New("capability: invalid configuration") // ErrInvalidPayload reports a malformed or semantically invalid payload. ErrInvalidPayload = errors.New("capability: invalid payload") // ErrNonCanonical reports a valid representation that is not the unique v1 encoding. ErrNonCanonical = errors.New("capability: non-canonical encoding") // ErrInvalidToken reports malformed token framing or protected metadata. ErrInvalidToken = errors.New("capability: invalid token") // ErrInvalidSignature reports that the protected token did not authenticate. ErrInvalidSignature = errors.New("capability: invalid signature") // ErrSigningFailed reports a signer failure without exposing its diagnostic. ErrSigningFailed = errors.New("capability: signing failed") // ErrKeyResolution reports a resolver failure without exposing its diagnostic. ErrKeyResolution = errors.New("capability: key resolution failed") // ErrAlgorithmMismatch reports an algorithm and key-type mismatch. ErrAlgorithmMismatch = errors.New("capability: algorithm mismatch") // ErrUnknownKey reports an unresolved key identifier. ErrUnknownKey = errors.New("capability: unknown key") // ErrKeyDisabled reports a key that policy has disabled without revoking it. ErrKeyDisabled = errors.New("capability: key disabled") // ErrKeyRevoked reports a key that policy has revoked. ErrKeyRevoked = errors.New("capability: key revoked") // ErrKeyNotActive reports a key outside its configured activation interval. ErrKeyNotActive = errors.New("capability: key not active") // ErrNotYetValid reports a capability used before its validity interval. ErrNotYetValid = errors.New("capability: not yet valid") // ErrExpired reports a capability used after its validity interval. ErrExpired = errors.New("capability: expired") ErrUnauthorized = errors.New("capability: unauthorized use") // ErrInvalidURL reports a URL or profile with ambiguous or unsafe semantics. ErrInvalidURL = errors.New("capability: invalid URL") // ErrURLBinding reports a valid capability presented for a different URL use. ErrURLBinding = errors.New("capability: URL binding mismatch") // ErrReplayExhausted reports a capability whose bounded uses were consumed. ErrReplayExhausted = errors.New("capability: use limit exhausted") // ErrReplayConflict reports inconsistent state for one capability identity. ErrReplayConflict = errors.New("capability: replay state conflict") // ErrConsumptionUnknown reports a store failure whose commit outcome is unknown. ErrConsumptionUnknown = errors.New("capability: consumption outcome unknown") // ErrRevoked reports authority matched by a configured revocation boundary. ErrRevoked = errors.New("capability: revoked") // ErrRevocationUnknown reports a revocation check that could not complete. ErrRevocationUnknown = errors.New("capability: revocation status unknown") // ErrAdapterProtocol reports a malformed durable-adapter response. ErrAdapterProtocol = errors.New("capability: adapter protocol violation") )
Functions ¶
func CanonicalPayload ¶
CanonicalPayload validates payload and returns its unique UTF-8 JSON encoding. Strings are preserved byte-for-byte: canonically equivalent Unicode forms remain distinct authority strings and are never normalized implicitly.
func Issue ¶
Issue validates and signs one canonical v1 payload.
Example ¶
package main
import (
"context"
"fmt"
"time"
"github.com/faustbrian/go-capability/v2"
)
func main() {
now := time.Date(2026, 8, 9, 12, 0, 0, 0, time.UTC)
key := []byte("0123456789abcdef0123456789abcdef")
signer, _ := capability.NewHMACSHA256Signer("example-key", key)
verifier, _ := capability.NewHMACSHA256Verifier(key)
payload := capability.Payload{
Version: 1, Issuer: "https://issuer.example",
Audiences: []string{"download"}, Bearer: true,
Resource: "reports/42", Operation: "download",
IssuedAt: now, NotBefore: now, ExpiresAt: now.Add(time.Minute),
ID: "example-capability",
}
token, _ := capability.Issue(context.Background(), payload, signer, capability.DefaultLimits())
keys, _ := capability.NewKeySet([]capability.Key{{Issuer: "https://issuer.example", ID: "example-key", Verifier: verifier}})
grant, _ := capability.Verify(context.Background(), token, keys, capability.VerifyOptions{Issuer: "https://issuer.example",
Now: now, Limits: capability.DefaultLimits(),
})
err := grant.Authorize(capability.Use{Issuer: "https://issuer.example",
Audience: "download", Resource: "reports/42", Operation: "download",
})
fmt.Println(err == nil)
}
Output: true
func SignURL ¶
func SignURL( ctx context.Context, payload Payload, request URLRequest, profile URLProfile, signer Signer, limits Limits, ) (string, error)
SignURL binds a capability to a canonical URL and inserts the token in the profile's signature parameter. Payload Resource and Operation must be empty because this function owns those authority fields.
Example ¶
package main
import (
"context"
"fmt"
"time"
"github.com/faustbrian/go-capability/v2"
)
func main() {
now := time.Date(2026, 8, 9, 12, 0, 0, 0, time.UTC)
signer, _ := capability.NewHMACSHA256Signer(
"example-key", []byte("0123456789abcdef0123456789abcdef"),
)
payload := capability.Payload{
Version: 1, Issuer: "https://issuer.example",
Audiences: []string{"download"}, Bearer: true,
IssuedAt: now, NotBefore: now, ExpiresAt: now.Add(time.Minute),
ID: "example-url",
}
profile := capability.URLProfile{
Name: "download-v1", SignatureParameter: "cap",
AllowedSchemes: []string{"https"},
AllowedAuthorities: []string{"files.example"},
QueryParameters: []string{"download"},
}
signed, _ := capability.SignURL(context.Background(), payload, capability.URLRequest{
Method: "GET", RawURL: "https://files.example/report/42?download=1",
}, profile, signer, capability.DefaultLimits())
fmt.Println(len(signed) > len("https://files.example/report/42?download=1"))
}
Output: true
Types ¶
type Algorithm ¶
type Algorithm string
Algorithm identifies a reviewed signature construction and its required key type.
type BoundedResolver ¶
type BoundedResolver struct {
// contains filtered or unexported fields
}
BoundedResolver constrains remote key lookups by algorithm, identifier size, and deadline.
func NewBoundedResolver ¶
func NewBoundedResolver(options BoundedResolverOptions) (*BoundedResolver, error)
NewBoundedResolver validates remote resolution policy.
func (*BoundedResolver) Resolve ¶
func (resolver *BoundedResolver) Resolve(ctx context.Context, keyID string, algorithm Algorithm) (ResolvedKey, error)
Resolve calls the remote source under the configured deadline and rechecks algorithm binding.
type BoundedResolverOptions ¶
type BoundedResolverOptions struct {
Source Resolver
Timeout time.Duration
AllowedAlgorithms []Algorithm
MaxKeyIDBytes int
}
BoundedResolverOptions limits a caller-provided remote key source. Source must honor context cancellation; this adapter creates no hidden goroutines.
type Consumption ¶
Consumption binds an exact authenticated issuer and capability ID to one immutable expiry and maximum-use bound. Issuer is required; stores must not merge different issuer namespaces even when their capability IDs match.
type ConsumptionResult ¶
ConsumptionResult is the committed use ordinal and remaining allowance.
type ConsumptionStore ¶
type ConsumptionStore interface {
Consume(context.Context, Consumption) (ConsumptionResult, error)
}
ConsumptionStore atomically increments a capability only when its committed use count remains below MaxUses. ErrCapacity, like ErrReplayExhausted and ErrReplayConflict, asserts that no use was committed. Custom adapters are trusted to return those classifications only for known no-consume outcomes. Any non-policy error may represent an unknown commit outcome and callers must fail closed rather than retry blindly.
type ConsumptionStoreFunc ¶
type ConsumptionStoreFunc func(context.Context, Consumption) (ConsumptionResult, error)
ConsumptionStoreFunc adapts a function to ConsumptionStore.
func (ConsumptionStoreFunc) Consume ¶
func (function ConsumptionStoreFunc) Consume(ctx context.Context, consumption Consumption) (ConsumptionResult, error)
Consume implements ConsumptionStore.
type Grant ¶
type Grant struct {
// contains filtered or unexported fields
}
Grant is authenticated capability authority. Its contents are copied so caller mutation cannot widen a previously verified grant.
func Verify ¶
func Verify(ctx context.Context, token string, resolver Resolver, options VerifyOptions) (Grant, error)
Verify authenticates and validates a token. It does not authorize an attempted resource operation; use Grant.Authorize for that separate step.
func VerifyURL ¶
func VerifyURL( ctx context.Context, request URLRequest, profile URLProfile, resolver Resolver, options VerifyOptions, ) (Grant, error)
VerifyURL authenticates the embedded capability and independently checks its method, authority, path, query, profile, and optional body-digest binding.
func (Grant) Authorize ¶
Authorize checks exact encoded authority separately from parsing and signature verification.
func (Grant) Consume ¶
func (grant Grant) Consume(ctx context.Context, store ConsumptionStore) (ConsumptionResult, error)
Consume atomically records one bounded use. Reusable grants do not require a store. Store errors retain only replay-policy, capacity, and safe context classifications, not the store's diagnostic text or arbitrary causes.
type Header ¶
type Header struct {
Version int `json:"v"`
Type string `json:"typ"`
Algorithm Algorithm `json:"alg"`
KeyID string `json:"kid"`
}
Header is protected token metadata. Algorithm is authenticated but is also checked against the trusted verifier returned by Resolver.
type Key ¶
type Key struct {
Issuer string
ID string
Verifier Verifier
Disabled bool
Revoked bool
NotBefore time.Time
NotAfter time.Time
}
Key is immutable verifier policy for one globally unique key ID owned by exactly one explicit issuer namespace.
type KeySet ¶
type KeySet struct {
// contains filtered or unexported fields
}
KeySet is an immutable in-process resolver suitable for explicit rotation overlap.
type Limits ¶
type Limits struct {
MaxTokenBytes int
MaxFieldBytes int
MaxAudiences int
MaxCaveats int
MaxCaveatBytes int
MaxLifetime time.Duration
MaxUses uint32
}
Limits bounds every attacker-controlled token and payload collection.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns the reviewed v1 resource limits.
type Parsed ¶
Parsed is a structurally valid canonical token. It is not authenticated and grants no authority until passed to Verify.
type Payload ¶
type Payload struct {
Version int
Issuer string
Audiences []string
Subject string
Bearer bool
Resource string
Operation string
IssuedAt time.Time
NotBefore time.Time
ExpiresAt time.Time
ID string
Tenant string
CorrelationID string
MaxUses uint32
Caveats map[string]string
}
Payload is the authority encoded by a v1 capability. Subject and Bearer are mutually exclusive. MaxUses zero means reusable; a positive value is an upper bound enforced by a replay store, not by signature verification alone.
type ResolvedKey ¶
type ResolvedKey struct {
// Issuer is the trusted namespace owning this key, not a token-derived claim.
Issuer string
Verifier Verifier
Disabled bool
Revoked bool
NotBefore time.Time
NotAfter time.Time
}
ResolvedKey is trusted key-policy state returned by a Resolver.
type ResolverFunc ¶
ResolverFunc adapts a function to Resolver.
func (ResolverFunc) Resolve ¶
func (function ResolverFunc) Resolve(ctx context.Context, keyID string, algorithm Algorithm) (ResolvedKey, error)
Resolve implements Resolver.
type RevocationChecker ¶
type RevocationChecker interface {
Check(context.Context, RevocationQuery) (bool, error)
}
RevocationChecker checks capability, key, subject, resource, and issued-before policy.
type RevocationCheckerFunc ¶
type RevocationCheckerFunc func(context.Context, RevocationQuery) (bool, error)
RevocationCheckerFunc adapts a function to RevocationChecker.
func (RevocationCheckerFunc) Check ¶
func (function RevocationCheckerFunc) Check(ctx context.Context, query RevocationQuery) (bool, error)
Check implements RevocationChecker.
type RevocationQuery ¶
type RevocationQuery struct {
Issuer string
Tenant string
CapabilityID string
KeyID string
Subject string
Resource string
IssuedAt time.Time
}
RevocationQuery is the complete authenticated identity checked after signature and time validation.
type Signer ¶
type Signer interface {
Algorithm() Algorithm
KeyID() string
Sign(context.Context, []byte) ([]byte, error)
}
Signer signs canonical protected bytes with an explicitly bound algorithm and key ID.
func NewEd25519Signer ¶
func NewEd25519Signer(keyID string, key ed25519.PrivateKey) (Signer, error)
NewEd25519Signer copies a standard-library private key into an Ed25519 signer.
type URLProfile ¶
type URLProfile struct {
Name string
SignatureParameter string
AllowRelative bool
AllowedSchemes []string
AllowedAuthorities []string
QueryParameters []string
RequireBodyDigest bool
}
URLProfile fixes every URL component whose interpretation affects authority. QueryParameters is an allowlist; duplicate parameters are always rejected.
func (URLProfile) Validate ¶
func (profile URLProfile) Validate(limits Limits) error
Validate checks that a profile is deterministic and bounded under limits.
type URLRequest ¶
URLRequest contains the already selected external request representation. BodyDigest, when required, is exactly a SHA-256 digest rather than body bytes.
type Use ¶
type Use struct {
Issuer string
Audience string
Subject string
Resource string
Operation string
Tenant string
Caveats map[string]string
}
Use describes one concrete application operation to authorize.
type Verifier ¶
Verifier authenticates canonical protected bytes with one bound algorithm.
func NewEd25519Verifier ¶
NewEd25519Verifier copies a standard-library public key into an Ed25519 verifier.
func NewHMACSHA256Verifier ¶
NewHMACSHA256Verifier copies key material into an HMAC-SHA-256 verifier.
type VerifyOptions ¶
type VerifyOptions struct {
// Issuer is selected by trusted application configuration. It is required
// and must match both the signed claim and the resolved key's owner.
Issuer string
Now time.Time
Skew time.Duration
Limits Limits
Revocations RevocationChecker
}
VerifyOptions defines trusted issuer selection, time, skew, and parser limits.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
http
Package capabilityhttp integrates verified signed-URL grants with net/http without hiding application authorization or bounded-use consumption.
|
Package capabilityhttp integrates verified signed-URL grants with net/http without hiding application authorization or bounded-use consumption. |
|
memory
Package capabilitymemory provides process-local replay and revocation adapters.
|
Package capabilitymemory provides process-local replay and revocation adapters. |
|
Package caphttp is the compatibility facade for the target-oriented HTTP adapter.
|
Package caphttp is the compatibility facade for the target-oriented HTTP adapter. |
|
Package memory is the compatibility facade for the target-oriented process-local replay and revocation adapter.
|
Package memory is the compatibility facade for the target-oriented process-local replay and revocation adapter. |
|
Package postgres provides durable atomic capability consumption through database/sql and PostgreSQL row locks.
|
Package postgres provides durable atomic capability consumption through database/sql and PostgreSQL row locks. |
|
Package valkey provides atomic bounded-use consumption through one Valkey EVAL operation.
|
Package valkey provides atomic bounded-use consumption through one Valkey EVAL operation. |