audit

type Actor struct {
	// Org is the tenant the action was taken IN — the EFFECTIVE org (X-Org-Id).
	// For all but one caller this is also the actor's own org. Empty for an
	// unauthenticated request.
	Org string `json:"org"`
	// Sub is the user id (IAM `sub`/`preferred_username`). Empty for a service
	// principal or an anonymous request.
	Sub string `json:"sub"`
	// Email is the validated user email, when present.
	Email string `json:"email,omitempty"`

	// Home is the actor's OWN org (the validated home-org claim, X-User-Owner),
	// recorded ONLY when it DIFFERS from Org — i.e. ONLY when this action was
	// taken by a platform SuperAdmin acting INSIDE ANOTHER TENANT.
	//
	// Recording it conditionally is what makes the field MEAN something: a
	// non-empty Home is, by construction, an impersonation event. Without it an
	// admin org-switch is indistinguishable from a native member of the target
	// org, because Org alone says "lux" in both cases — the impersonation fact
	// was being destroyed at the moment of recording.
	//
	// HASH COMPATIBILITY (why omitempty is load-bearing, not style): the chain
	// hashes the canonical JSON of the record (canonicalBytes). An omitempty
	// field that is empty marshals to NOTHING, so every pre-existing record —
	// and every ordinary same-org record written from now on — produces byte-
	// identical canonical JSON to before this field existed. Existing hashes
	// still verify. See TestVerify_HomeFieldIsHashCompatible.
	Home string `json:"home,omitempty"`
}

type AuthContext struct {
	Method  string `json:"method"`
	IsAdmin bool   `json:"isAdmin"`
}

type Checkpoint struct {
	Time  time.Time `json:"time"`
	Count uint64    `json:"count"`
	Head  string    `json:"head"`
}

type CheckpointFunc func(cp Checkpoint)

type CheckpointSink interface {
	Checkpoint(ctx context.Context, cp Checkpoint) error
}

type Filter struct {
	Org  string // actor_org exact match (the org acted IN)
	Sub  string // actor_sub exact match (a specific user)
	Home string // actor_home exact match — the org the actor came FROM.
	// Impersonated restricts to CROSS-ORG actions only (actor_home <> ”), which
	// is the question this control exists to answer: "show me every time a
	// platform admin acted inside a tenant that was not their own." Without it an
	// auditor would have to scan the whole trail to find the events that matter
	// most.
	Impersonated bool
	Action       string    // action exact match
	Resource     string    // res_type exact match
	ResourceID   string    // res_id exact match (a specific resource instance)
	Result       string    // outcome result: success|deny|error
	Since        time.Time // ts >= Since (UTC)
	Until        time.Time // ts <= Until (UTC)
	Limit        int       // max rows (default 100, cap 1000)
	Offset       int       // pagination offset
}

type Integrity struct {
	// OK is true iff every record's stored hash equals the recomputed hash AND the
	// chain links are continuous (each PrevHash == the prior record's Hash, seqs
	// gapless from 0).
	OK bool `json:"ok"`
	// Count is the number of records walked.
	Count uint64 `json:"count"`
	// HeadHash is the hash of the last record (or the genesis anchor for an empty
	// chain). Pin this externally over time to detect tail-truncation.
	HeadHash string `json:"headHash"`
	// BrokenAt is the seq of the FIRST record that failed verification, or -1 when
	// OK. Reason describes the break (recomputed-hash mismatch, prev-hash
	// discontinuity, or a seq gap).
	BrokenAt int64  `json:"brokenAt"`
	Reason   string `json:"reason,omitempty"`
}

type Mirror interface {
	// Append writes one sealed record to the projection. A returned error is
	// logged and dropped by the Recorder — the mirror never gates a request.
	Append(ctx context.Context, r Record) error
}

type Outcome struct {
	Result string `json:"result"`
	Status int    `json:"status"`
	Reason string `json:"reason,omitempty"`
}

type Record struct {
	// Seq is the strictly-increasing chain position (0-based). It is assigned by
	// the Recorder under its lock, so it is a true total order with no gaps.
	Seq uint64 `json:"seq"`

	// Time is the UTC event timestamp (RFC3339Nano).
	Time time.Time `json:"time"`

	// Actor / Action / Resource / Auth / Outcome — the AU-3 "content of audit
	// records" core: who, what, on what, how-authenticated, with what result.
	Actor    Actor       `json:"actor"`
	Action   string      `json:"action"`
	Resource Resource    `json:"resource"`
	Auth     AuthContext `json:"auth"`
	Outcome  Outcome     `json:"outcome"`

	// SourceIP + UserAgent — the AU-3 "source of the event" fields.
	SourceIP  string `json:"sourceIp,omitempty"`
	UserAgent string `json:"userAgent,omitempty"`

	// RequestID correlates the record to the request-line log and any downstream
	// trace (the X-Request-Id the pipeline mints).
	RequestID string `json:"requestId,omitempty"`

	// Method + Path are the HTTP verb and route for a request-sourced event.
	Method string `json:"method,omitempty"`
	Path   string `json:"path,omitempty"`

	// Before / After capture a mutation's prior and resulting state for the
	// AU-required "before/after" on config-affecting changes. They are populated
	// ONLY by explicit emit points and ONLY after Redact has stripped secrets —
	// the HTTP middleware never sets them (it never reads bodies), so a secret in
	// a request body can never leak here. Raw JSON so any shape round-trips.
	Before json.RawMessage `json:"before,omitempty"`
	After  json.RawMessage `json:"after,omitempty"`

	// PrevHash is the hash of record Seq-1 (hex). For the genesis record (Seq 0)
	// it is genesisPrevHash. Hash is this record's hash. Neither participates in
	// its own hash computation (both are zeroed in canonicalBytes).
	PrevHash string `json:"prevHash"`
	Hash     string `json:"hash"`
}

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

type Resource struct {
	Type string `json:"type"`
	ID   string `json:"id,omitempty"`
}

type Wire struct {
	Seq   uint64 `json:"seq"`
	Time  string `json:"time"`
	Org   string `json:"org"`
	Sub   string `json:"sub"`
	Email string `json:"email,omitempty"`
	// Home is present ONLY on a cross-org action: the org the actor came FROM,
	// while Org is the org they acted IN. A console row carrying `home` is a
	// platform-admin impersonation and should be rendered as one.
	Home       string `json:"home,omitempty"`
	Action     string `json:"action"`
	Resource   string `json:"resource"`
	ResourceID string `json:"resourceId,omitempty"`
	Method     string `json:"method,omitempty"`
	Path       string `json:"path,omitempty"`
	Result     string `json:"result"`
	Status     int    `json:"status"`
	Reason     string `json:"reason,omitempty"`
	SourceIP   string `json:"sourceIp,omitempty"`
	UserAgent  string `json:"userAgent,omitempty"`
	RequestID  string `json:"requestId,omitempty"`
	IsAdmin    bool   `json:"isAdmin"`
	Auth       string `json:"authMethod,omitempty"`
	Hash       string `json:"hash"`
	PrevHash   string `json:"prevHash"`
}