jose

type Claims ¶

type Claims struct {
	Issuer    string
	Subject   string
	Audience  []string
	IssuedAt  time.Time
	ExpiresAt time.Time
	NotBefore time.Time
	JTI       string
	// Raw is the full decoded claim map for fields not promoted above (vendor extensions,
	// custom claims, etc.). Apps cast values themselves.
	Raw map[string]any
}

Claims is the verified claim set extracted from a successfully decrypted-and-verified inbound JOSE payload. The middleware sets it on the request context so application handlers can enforce iat/exp/jti policies (per the v1 decision: framework verifies the signature, applications enforce timing).

All fields are zero-valued if absent from the JWS payload; nothing here is required at the framework layer — apps that don't care about a particular claim simply ignore it.

func ClaimsFromContext(ctx context.Context) *Claims

type Direction ¶

type Direction int

Direction indicates which side of the request/response pipeline a Policy applies to.

const (
	DirectionInbound  Direction = iota // request body: decrypt + verify
	DirectionOutbound                  // response body: sign + encrypt
)

func (d Direction) String() string

type Error ¶

type Error struct {
	Sentinel error
	Code     string
	Status   int
	Message  string
	Kid      string
	Alg      string
	Enc      string
	Cause    error
}

Error is the structured value returned by every jose package operation that fails. It carries diagnostic fields (Kid, Alg, Enc) for logging and an HTTP-mapped Code/Status for response shaping. Use errors.Is(err, ErrDecryptFailed) for sentinel comparisons.

The Cause field MUST NOT be exposed to peers — it can leak information about which key was tried or which library detected the failure. Server middleware logs Cause; only Code and the constant-time generic Message reach the wire.

func (e *Error) Error() string

func (e *Error) Is(target error) bool

func (e *Error) Unwrap() error

type Header ¶

type Header struct {
	Kid string
	Alg string
	Enc string
	Cty string
}

Header (jose-package level) is the diagnostic header shape exposed to callers, distinct from the internal cryptoadapter.Header to insulate consumers from library churn.

type KeyResolver ¶

type KeyResolver interface {
	PrivateKey(kid string) (*rsa.PrivateKey, error)
	PublicKey(kid string) (*rsa.PublicKey, error)
}

KeyResolver abstracts key lookup so the jose package does not depend directly on app.KeyStore. This keeps the door open for future JWKS-URL backed resolvers without breaking callers, and makes testing trivial (NewTestResolver in jose/testing/).

Public/private semantics map to JOSE roles:

• PrivateKey: used to decrypt inbound JWE and sign outbound JWS.
• PublicKey: used to verify inbound JWS and encrypt outbound JWE.

Implementations MUST return the registered ErrKidUnknown sentinel (wrapped in *Error) when a kid is not configured, so callers can distinguish unknown-key from other failures via errors.Is.

type KeyStoreLike ¶

type KeyStoreLike interface {
	PrivateKey(name string) (*rsa.PrivateKey, error)
	PublicKey(name string) (*rsa.PublicKey, error)
}

KeyStoreLike is the minimal subset of app.KeyStore that the resolver consumes. Defining it locally lets jose/ wrap any compatible store without importing app/, which would create an app → server → jose → app cycle once the server module wires the resolver via app/module_registry.go.

type KeyStoreResolver ¶

type KeyStoreResolver struct {
	// contains filtered or unexported fields
}

KeyStoreResolver adapts a KeyStoreLike (typically an app.KeyStore) to KeyResolver. It is the default resolver wired into the server when a keystore module is registered.

func NewKeyStoreResolver(ks KeyStoreLike) *KeyStoreResolver

func (r *KeyStoreResolver) PrivateKey(kid string) (*rsa.PrivateKey, error)

func (r *KeyStoreResolver) PublicKey(kid string) (*rsa.PublicKey, error)

type OpenHeader ¶

type OpenHeader struct {
	JWE Header
	JWS Header
}

OpenHeader holds the diagnostic headers from both JOSE layers, surfaced to the caller so the middleware can log them. Never includes plaintext.

type Policy ¶

type Policy struct {
	Direction Direction

	// Inbound (DirectionInbound) — both required.
	DecryptKid string // our private key kid (jose: decrypt=...)
	VerifyKid  string // peer public key kid (jose: verify=...)

	// Outbound (DirectionOutbound) — both required.
	SignKid    string // our private key kid (jose: sign=...)
	EncryptKid string // peer public key kid (jose: encrypt=...)

	// Algorithms — defaults applied by the parser if tag omits them.
	SigAlg jose.SignatureAlgorithm
	KeyAlg jose.KeyAlgorithm
	Enc    jose.ContentEncryption
	Cty    string
}

Policy captures the JOSE configuration declared by a request or response struct's jose: tag. Inbound policies populate DecryptKid/VerifyKid; outbound populate SignKid/EncryptKid. SigAlg/KeyAlg/Enc/Cty fall back to package defaults when unset.

A Policy is constructed once at registration time by the scanner, validated against the KeyResolver, and cached in the registry — never re-parsed per request.

func ParseTag(tagValue string, dir Direction) (*Policy, error)

func PolicyFromContext(ctx context.Context) *Policy

func ScanType(t reflect.Type, dir Direction) (*Policy, error)

func (p *Policy) Validate() error

type PolicyRegistry ¶

type PolicyRegistry struct {
	// contains filtered or unexported fields
}

PolicyRegistry caches scanned + resolved Policies keyed by (reflect.Type, Direction). Including direction is essential: the same struct type can legitimately be scanned for both DirectionInbound and DirectionOutbound (e.g., a shared envelope used as both a request and response on different routes), and the resulting policies have different required keys. A type-only key would return the wrong policy on the second scan.

Mirrors the pattern in database/internal/columns/registry.go:24,89 (sync.Map + LoadOrStore) which is proven thread-safe and lock-free on the hot path.

The cache stores nil to mean "this type was scanned and has no JOSE policy" — distinct from "this type has not been scanned yet" (cache miss). This avoids re-scanning untagged types on every request, which would otherwise dominate the request hot path for non-JOSE routes.

func NewPolicyRegistry() *PolicyRegistry

func (r *PolicyRegistry) LoadOrScan(t reflect.Type, dir Direction) (*Policy, error)

func (r *PolicyRegistry) Store(t reflect.Type, p *Policy)