auth

type AccessMode string

type AuthDecisionEvent struct {
	Time    time.Time
	TraceID string
	// Access and policy context (immutable snapshot at decision time)
	AccessMode    AccessMode
	RequiredLevel RequiredLevel
	HandlerKind   HandlerKind
	Frontend      string
	Outcome       DecisionOutcome
	ReasonCode    string
	// Principal is a safe snapshot: IDs and non-secret display metadata only.
	PrincipalID          string
	PrincipalDisplayName string
	PrincipalRoles       []string
	// PrincipalSafeClaims is keyed by non-empty trimmed claim names; values must remain empty
	// on audit paths—do not place secret-bearing strings in map values.
	PrincipalSafeClaims map[string]string
	// Device is a non-secret snapshot: identifiers and redacted fingerprint only.
	DeviceID          string
	DeviceKeyID       string
	DeviceFingerprint string
	// Challenge, when applicable, is non-secret metadata.
	ChallengeKind    ChallengeKind
	ChallengeSummary string
	// Scope is an optional safe principal/scope snapshot from a trusted auth decision. It is
	// nil when no scope was supplied. Raw secrets, transport headers, and resume authority
	// must never be placed here (requirements 6.1, 2.6, 5.2).
	Scope *scope.PrincipalScopeView
}

type Challenge struct {
	Kind       ChallengeKind
	ReasonCode string
	// Summary is a short operator-safe, non-secret message (e.g. "SSO sign-in required").
	Summary string
}

type ChallengeKind string

type Decision struct {
	Outcome   DecisionOutcome
	Principal execview.PrincipalView
	Device    DeviceIdentity
	// SatisfiedLevel is the auth level the decision satisfied, if any, relative to policy.
	SatisfiedLevel RequiredLevel
	Challenge      Challenge
	// ReasonCode is a stable, machine-oriented reason (e.g. "invalid_api_key", "remote_denied").
	ReasonCode string
	// Scope carries an optional authoritative safe principal/scope snapshot supplied by
	// trusted auth code. It is nil for legacy principal-only decisions. Raw bearer/API/OAuth/
	// resume tokens and transport headers must never be placed here (requirements 2.1, 2.5, 2.6).
	Scope *scope.PrincipalScopeView
	// SubmissionAuthority carries optional trusted current-turn or continuation
	// classification. Client payload metadata and headers are never promoted to
	// this field; absence leaves prompt-priced submission charging unsupported.
	SubmissionAuthority *submission.Authority
}

type DecisionOutcome string

type DeviceIdentity struct {
	ID          string
	KeyID       string
	Fingerprint string
}

type HandlerKind string

type InboundCallMeta struct {
	TraceID  string
	Frontend string
	Method   string
	Path     string
	// ClientAddr is a transport-level remote address (for example host:port). In some jurisdictions
	// it may be treated as personal data; consider redaction and retention policies in logs and audits.
	ClientAddr string
	// AuthorizationBearer is the raw token from an HTTP Authorization header only when the scheme
	// is Bearer; otherwise empty. Treat as secret at rest and in logs.
	AuthorizationBearer string
	// SessionHint is a client-supplied resume or session handle; may be secret if it authorizes.
	SessionHint string
}

type RequiredLevel string

type SessionCertainty string

type SessionStartEvent struct {
	Time                 time.Time
	TraceID              string
	AccessMode           AccessMode
	RequiredLevel        RequiredLevel
	HandlerKind          HandlerKind
	Frontend             string
	SessionID            string
	ClientSessionRef     string
	ALegID               string
	Certainty            SessionCertainty
	IsNew                bool
	PrincipalID          string
	PrincipalDisplayName string
}