ephemeral

Documentation

Overview

Package ephemeral provides in-memory implementations of keys.KeyManager and keys.ClientKeySource — for local development and testing only. Never production.

KeyManager generates fresh keys once at process startup and never persists them. Restarting the process invalidates every previously issued token and everything a client cached from this server's own JWKS — there is no key rollover, no durability, nothing to recover after a crash. That's the right tradeoff for a short local development session; it is never the right tradeoff for anything that needs to survive a restart.

Index

• type ClientKeySource
  • func NewClientKeySource(fetcher *fapihttp.Client, specs []ClientKeySpec, opts ...Option) (*ClientKeySource, error)
  • func (s *ClientKeySource) ResolveVerificationKeys(ctx context.Context, req keys.ClientKeyRequest) (keys.VerificationKeySet, error)
• type ClientKeySpec
• type KeyManager
  • func NewKeyManager(purposes map[keys.SigningPurpose]fapi.SignatureAlgorithm) (*KeyManager, error)
  • func NewKeyManagerWithDecryption(signingPurposes map[keys.SigningPurpose]fapi.SignatureAlgorithm, ...) (*KeyManager, error)
  • func (m *KeyManager) EncryptionPublicKey(_ context.Context, purpose keys.DecryptionPurpose, ...) (keys.PublicKeyInfo, error)
  • func (m *KeyManager) PublicKey(_ context.Context, purpose keys.SigningPurpose, _ fapi.SignatureAlgorithm) (keys.PublicKeyInfo, error)
  • func (m *KeyManager) Sign(_ context.Context, req keys.SigningRequest) (keys.Signature, error)
  • func (m *KeyManager) UnwrapContentEncryptionKey(_ context.Context, req keys.UnwrapRequest) ([]byte, error)
• type Option
  • func WithCacheTTL(d time.Duration) Option

Types

type ClientKeySource

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

ClientKeySource resolves each registered client's verification keys, either from an inline static JWKS or by fetching one live via fapihttp.Client — which already applies the SSRF/size-limit/ content-type hardening ARCHITECTURE.md design rule 6 requires for exactly this case, so this type reuses it rather than issuing its own HTTP requests. See the package doc comment for why this is development/testing only.

func NewClientKeySource

func NewClientKeySource(fetcher *fapihttp.Client, specs []ClientKeySpec, opts ...Option) (*ClientKeySource, error)

NewClientKeySource builds a ClientKeySource from specs, parsing every inline static JWKS up front so a malformed one fails at construction rather than on the first request that needs it.

func (*ClientKeySource) ResolveVerificationKeys

func (s *ClientKeySource) ResolveVerificationKeys(ctx context.Context, req keys.ClientKeyRequest) (keys.VerificationKeySet, error)

ResolveVerificationKeys implements keys.ClientKeySource.

type ClientKeySpec

type ClientKeySpec struct {
	ClientID fapi.ClientID

	// JWKS is an inline, already-known JWK Set. Takes priority over
	// JWKSURI when both are set.
	JWKS []byte

	// JWKSURI is fetched live (and cached) when JWKS is empty.
	JWKSURI string
}

ClientKeySpec is one registered client's verification key material — either an inline static JWKS or a JWKS URI to fetch live. Deliberately carries only what ClientKeySource needs (not a storage.RegisteredClient or anything client-repository-shaped): whether a client is registered at all is storage's concern, not this one's.

type KeyManager

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

KeyManager is a keys.KeyManager backed by fresh in-memory keys generated once at construction, one per active signing purpose. See the package doc comment for why this is development/testing only.

It also implements keys.Decrypter when constructed via NewKeyManagerWithDecryption (see decrypter.go) — decryption is opt-in since most callers never need it, and decryption is not merely an addition to keys.KeyManager (the underlying key types and use cases differ), so plain NewKeyManager leaves the decryption field nil.

func NewKeyManager

func NewKeyManager(purposes map[keys.SigningPurpose]fapi.SignatureAlgorithm) (*KeyManager, error)

NewKeyManager generates one key per purpose in purposes, sized for the paired algorithm (ECDSA P-256 for ES256, RSA-2048 for PS256, Ed25519 for EdDSA — the three algorithms this module supports).

func NewKeyManagerWithDecryption

func NewKeyManagerWithDecryption(
	signingPurposes map[keys.SigningPurpose]fapi.SignatureAlgorithm,
	decryptionPurposes map[keys.DecryptionPurpose]fapi.KeyManagementAlgorithm,
) (*KeyManager, error)

NewKeyManagerWithDecryption is NewKeyManager plus one decryption key per purpose in decryptionPurposes, sized for the paired algorithm (RSA-2048 for RSAOAEP256, ECDH P-256 for ECDHESA256KW — the only two algorithms this module supports). The returned *KeyManager implements both keys.KeyManager and keys.Decrypter.

func (*KeyManager) EncryptionPublicKey

func (m *KeyManager) EncryptionPublicKey(_ context.Context, purpose keys.DecryptionPurpose, _ fapi.KeyManagementAlgorithm) (keys.PublicKeyInfo, error)

EncryptionPublicKey implements keys.Decrypter.

func (*KeyManager) PublicKey

func (m *KeyManager) PublicKey(_ context.Context, purpose keys.SigningPurpose, _ fapi.SignatureAlgorithm) (keys.PublicKeyInfo, error)

PublicKey implements keys.KeyManager.

func (*KeyManager) Sign

func (m *KeyManager) Sign(_ context.Context, req keys.SigningRequest) (keys.Signature, error)

Sign implements keys.KeyManager.

func (*KeyManager) UnwrapContentEncryptionKey

func (m *KeyManager) UnwrapContentEncryptionKey(_ context.Context, req keys.UnwrapRequest) ([]byte, error)

UnwrapContentEncryptionKey implements keys.Decrypter. The private key never leaves this method — UnwrapCEK performs the RSA-OAEP-256 or ECDH-ES+A256KW recovery internally and returns only the resulting CEK bytes, the same "never hand back the private key" contract Sign already honors for signing purposes.

type Option

type Option func(*ClientKeySource)

Option configures a ClientKeySource.

func WithCacheTTL

func WithCacheTTL(d time.Duration) Option

WithCacheTTL overrides how long a fetched client JWKS is trusted before being re-fetched. Defaults to 5 minutes.