samesame

type AgentMember struct {
	// Key is the dictionary member key. It is empty for the legacy string
	// form of the header.
	Key string

	// Type is the member's type parameter, AgentTypeDirectory when absent.
	Type string

	// Value is the URI string exactly as sent.
	Value string

	// Identifier is the URL a verifier resolves for this member. It is nil
	// when the member must be ignored; Err then says why.
	Identifier *url.URL

	Err error
}

type ChallengeOptions struct {
	// Label is the requested signature label and Signature-Agent member key.
	// Defaults to DefaultLabel.
	Label string

	// Nonce, when set, asks the agent to sign with this exact nonce. The
	// caller is responsible for remembering and checking it.
	Nonce string
}

type Directory struct {
	Keys []Key

	// Invalid holds one error per key that was dropped while parsing. The
	// protocol draft says verifiers should reject malformed entries, so one
	// bad key does not reject the whole directory.
	Invalid []error
}

type DirectoryHandlerOptions struct {
	// Authorities lists the hosts, as sent in the Host header and with any
	// non-default port, that this directory is served for, such as
	// "bot.example". Required. Directory response signatures bind the keys
	// to the request's authority (Appendix B.1), so signing for any Host a
	// client sends would hand out proofs for other domains. Requests for
	// other hosts get 421 Misdirected Request.
	Authorities []string

	// MaxAge is sent as Cache-Control max-age. Defaults to
	// DefaultDirectoryMaxAge.
	MaxAge time.Duration

	// SignatureLifetime is the expires - created of each directory response
	// signature. Defaults to DefaultDirectorySignatureLifetime.
	SignatureLifetime time.Duration
}

type DirectoryOptions struct {
	// MaxKeys caps the number of keys a directory may list (protocol draft
	// Section 6.7). Zero means DefaultMaxKeys.
	MaxKeys int

	// AllowTestKeys accepts the published RFC 9421 test keys. Only tests
	// should set this (protocol draft Section 6.8).
	AllowTestKeys bool
}

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

type FetcherOptions struct {
	// Directory controls how fetched directories are parsed.
	Directory DirectoryOptions

	// Timeout bounds each fetch, including reading the body. Defaults to
	// DefaultFetchTimeout.
	Timeout time.Duration

	// MaxBodySize caps the directory size after content decoding. Defaults
	// to DefaultMaxDirectorySize.
	MaxBodySize int64

	// MinTTL and MaxTTL clamp how long a fetched directory is cached. TTL
	// is used when the response has no caching headers.
	MinTTL, MaxTTL, TTL time.Duration

	// NegativeTTL is the base backoff after a failed fetch. It grows
	// exponentially with consecutive failures, is raised to any
	// Retry-After, and never exceeds MaxNegativeTTL.
	NegativeTTL time.Duration

	// MaxCacheEntries caps the number of cached directories. Defaults to
	// DefaultMaxCacheEntries.
	MaxCacheEntries int

	// MaxConcurrentFetches caps fetches in flight across all origins.
	// Fetches of the same identifier are coalesced, and a directory
	// identifier is one per origin, so each origin already has at most one
	// fetch in flight (protocol draft Appendix C.3). Defaults to
	// DefaultMaxConcurrentFetches.
	MaxConcurrentFetches int

	// ClockSkew is the tolerance for directory response signature times.
	// Defaults to DefaultClockSkew.
	ClockSkew time.Duration

	// AllowedHosts, when set, is the only set of hosts (as in URL.Host)
	// that may be fetched.
	AllowedHosts []string

	// AllowPrivateAddresses permits fetching from loopback, private,
	// link-local, and other non-public addresses. Only tests should set it.
	AllowPrivateAddresses bool

	// TLSConfig is used for fetches, for example to trust a test CA.
	TLSConfig *tls.Config

	// VerifyDirectorySignatures keeps only keys that carry a valid directory
	// response signature (protocol draft Appendix B.1). The draft lets
	// verifiers use directly resolved keys without this proof, so it is off
	// by default.
	VerifyDirectorySignatures bool

	// Now returns the current time. Defaults to time.Now.
	Now func() time.Time
}

type Key struct {
	// ID is the base64url JWK SHA-256 thumbprint (RFC 7638, RFC 8037). A
	// signature's keyid parameter must match it.
	ID string

	// JWK is the public key.
	JWK jwk.Key

	// NotBefore and Expires come from the nbf and exp members, and are zero
	// when absent. The protocol draft does not define these members, so
	// honoring them is local policy.
	NotBefore time.Time
	Expires   time.Time
	// contains filtered or unexported fields
}

type KeyResolver interface {
	Resolve(ctx context.Context, identifier *url.URL) (*Directory, error)
}

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

type NonceStore interface {
	CheckAndRecord(ctx context.Context, scope, nonce string, until time.Time) (fresh bool, err error)
}

type Outcome int

type Result struct {
	Outcome Outcome

	// Label is the signature's label in Signature and Signature-Input.
	Label string

	// KeyID is the key thumbprint. When Identifier is nil, it is the only
	// identity the request has.
	KeyID string

	// Identifier is the resolved key directory URL the request is attributed
	// to, or nil when the key came from StaticKeys.
	Identifier *url.URL

	// Key is the public key the signature verified with.
	Key jwk.Key

	Created time.Time
	Expires time.Time
	Nonce   string

	// NonceChecked is true when a NonceStore saw this nonce for the first
	// time. It is false when there was no nonce or no NonceStore.
	NonceChecked bool
}

type SignatureAgent struct {
	// Legacy is true when the header used the deprecated single String Item
	// form. Its one member then has an empty Key.
	Legacy bool

	Members map[string]AgentMember
}

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

type SignerOptions struct {
	// AgentOrigin is the https origin that serves this agent's key directory,
	// such as "https://bot.example". It is sent in Signature-Agent. Required:
	// the protocol draft (Section 4.3) says a signed request MUST carry
	// Signature-Agent.
	AgentOrigin string

	// Label is the Signature / Signature-Input dictionary key. Defaults to
	// DefaultLabel.
	Label string

	// AgentKey is the Signature-Agent dictionary key. Defaults to Label.
	AgentKey string

	// Expiry is how long each signature is valid. Defaults to DefaultExpiry
	// and may not exceed MaxExpiry.
	Expiry time.Duration

	// DisableNonce omits the nonce parameter. By default each signature gets
	// a random 64-byte nonce so verifiers can detect replays.
	DisableNonce bool
}

type StaticDirectory struct {
	// Body is the directory JSON, byte for byte what NewDirectoryHandler
	// serves.
	Body []byte

	// Header holds the Content-Type, Cache-Control, Content-Digest,
	// Signature-Input, and Signature fields to send with Body.
	Header http.Header

	// Expires is when the signatures stop being valid. Generate new ones
	// before then.
	Expires time.Time
}

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

type VerifierOptions struct {
	// Resolver fetches key directories named by Signature-Agent. When nil,
	// only StaticKeys are used.
	Resolver KeyResolver

	// StaticKeys are keys known out of band. A request verified with one of
	// them is identified only by its key thumbprint, never by a URL
	// (protocol draft Section 4.3).
	StaticKeys []crypto.PublicKey

	// AllowTestKeys accepts the published RFC 9421 test keys in StaticKeys.
	// Only tests should set this.
	AllowTestKeys bool

	// MaxValidity caps expires - created. Zero means DefaultMaxValidity.
	MaxValidity time.Duration

	// ClockSkew is the tolerance applied to created and expires. Zero means
	// DefaultClockSkew.
	ClockSkew time.Duration

	// MaxSignatures caps how many web-bot-auth signatures in one request are
	// examined. Zero means DefaultMaxSignatures.
	MaxSignatures int

	// NonceStore, when set, rejects signatures whose nonce was already seen.
	NonceStore NonceStore

	// RequireNonce rejects signatures without a nonce. It only makes sense
	// with a NonceStore.
	RequireNonce bool

	// Scheme returns the scheme the client used. Behind a reverse proxy that
	// terminates TLS, set this to read a trusted forwarded header. The
	// default is "https" when r.TLS is set and "http" otherwise.
	Scheme func(r *http.Request) string

	// AllowInsecure accepts signatures on plaintext HTTP requests. The
	// protocol draft (Section 6.1) says origins SHOULD refuse them.
	AllowInsecure bool

	// Now returns the current time. Defaults to time.Now.
	Now func() time.Time
}

type VerifyError struct {
	Outcome Outcome
	Label   string // signature label, empty when not specific to one
	Err     error
}