stir

type AttestationLevel string

type HTTPFetcher struct {
	// HTTPClient is used for all GETs. Default: http.Client with
	// FetchTimeout. Inject a custom one for tests or to pin TLS.
	HTTPClient *http.Client

	// RootCAs is the STI-PA trust pool. nil → system roots (NOT
	// recommended in production; STI certs are issued by industry-
	// specific CAs, not WebPKI).
	RootCAs *x509.CertPool

	// IntermediateCAs is the optional intermediate pool — STI chains
	// typically have one intermediate cert between the leaf and the
	// STI-PA root. The fetcher will also accept intermediates served
	// inline in the x5u response.
	IntermediateCAs *x509.CertPool

	// CacheTTL is how long a successful lookup is cached. Zero →
	// defaultCertCacheTTL.
	CacheTTL time.Duration

	// NegativeCacheTTL is how long a failed lookup is cached. Zero
	// → defaultCertNegativeTTL.
	NegativeCacheTTL time.Duration

	// FetchTimeout caps one HTTP GET. Zero → defaultFetchTimeout.
	FetchTimeout time.Duration

	// Now is the clock function used for cache TTL and cert
	// notBefore/notAfter checks. Default time.Now. Injected for
	// deterministic tests.
	Now func() time.Time

	// SkipChainVerify disables chain validation. **Test-only.** When
	// true, only the PEM parse + key-type check runs. Never set this
	// in production — it accepts any cert as legitimate.
	SkipChainVerify bool
	// contains filtered or unexported fields
}

type IdentityHeader struct {
	// Passport is the compact-form JWS (b64.b64.b64). Caller passes
	// this to VerifyPassport after fetching the cert.
	Passport string
	// Info is the x5u URL (cert fetch). Required per RFC 8224 §4.1.
	Info string
	// Alg is the JWS algorithm hint duplicated from the JOSE header.
	// "ES256" is the only value SHAKEN supports.
	Alg string
	// Ppt is the PASSporT extension type ("shaken", "div", "rph").
	// Empty when the PASSporT is a base RFC 8225 token.
	Ppt string
}

type PassportClaims struct {
	IAT    int64           `json:"iat"`
	Orig   PassportParty   `json:"orig"`
	Dest   PassportDestSet `json:"dest"`
	Attest string          `json:"attest,omitempty"` // SHAKEN only
	OrigID string          `json:"origid,omitempty"` // SHAKEN only; UUID for traceback
}

type PassportDestSet struct {
	TN  []string `json:"tn,omitempty"`
	URI []string `json:"uri,omitempty"`
}

type PassportHeader struct {
	Alg string `json:"alg"`
	Ppt string `json:"ppt,omitempty"`
	Typ string `json:"typ"`
	X5u string `json:"x5u"`
}

type PassportParty struct {
	TN  string `json:"tn,omitempty"`
	URI string `json:"uri,omitempty"`
}

type SignedPassport struct {
	Compact string
	Header  PassportHeader
	Claims  PassportClaims
}

type Verdict struct {
	Code     VerdictCode
	Reason   string          // human-readable detail
	Passport *SignedPassport // populated on pass + most failure modes
	Header   *IdentityHeader // populated when the header parsed OK
}

type VerdictCode int

type Verifier struct {
	Fetcher X5UFetcher

	// MaxAge is how old the JWS `iat` claim is allowed to be before
	// the verifier returns VerdictStale (RFC 8224 §6.3.1 anti-replay).
	// Zero → 60s, matching the RFC SHOULD recommendation.
	MaxAge time.Duration

	// Now is the clock used for staleness checks. Default time.Now;
	// inject for deterministic tests.
	Now func() time.Time
}

type VerifyOptions struct {
	// FromTN is the SIP From header's TN (E.164, leading +). When
	// non-empty, the verifier checks that PASSporT.orig.tn matches.
	// Empty disables the check (useful for URI-only origins).
	FromTN string

	// FromURI is the SIP From header's URI. When non-empty AND the
	// PASSporT's orig is URI-form, the verifier checks for equality.
	FromURI string

	// RequiredPpt: when non-empty, the JWS header's `ppt` MUST equal
	// this value. Typical: "shaken" for North American inbound.
	RequiredPpt string

	// RequiredAttests: when non-empty, the PASSporT's `attest` MUST
	// be one of these (e.g. []{"A","B"} to reject C-attest gateway
	// calls). Empty allows any value.
	RequiredAttests []string
}

type X5UFetcher interface {
	// Fetch returns the leaf cert for x5uURL. Implementations are
	// expected to cache successful + failed lookups appropriately.
	// The returned cert's PublicKey is the *ecdsa.PublicKey used to
	// verify the PASSporT signature.
	Fetch(ctx context.Context, x5uURL string) (*x509.Certificate, error)
}