authz

type Actor struct {
	Kind       ActorKind
	UserID     uuid.UUID
	CapacityID uuid.UUID // zero for system/webhook actors
	System     string    // "outbox-relay", "webhook:payments"
	TenantID   uuid.UUID
	// ImpersonatorUserID is set when a support actor impersonates a user; both
	// identities are audited and impersonation is policy-restricted (01 §3).
	ImpersonatorUserID uuid.UUID
	// BreakGlass marks an actor operating under an activated break-glass grant;
	// every decision it produces is audited and bannered.
	BreakGlass bool
	// Scopes is the explicit permission set of a machine principal (API key /
	// service principal). It is meaningful only for ActorSystem actors: a scope
	// authorizes like an RBAC grant but remains subject to ABAC deny policies.
	// Human and internal-system actors leave it empty and are unaffected.
	Scopes []string
	// AMR is the authentication-methods-references set surfaced from the IdP token
	// (e.g. ["pwd","mfa","otp"]). It drives step-up enforcement and the env.mfa
	// ABAC attribute (roadmap S3).
	AMR []string
}

type ActorKind string

type Assignment struct {
	ID        uuid.UUID
	RoleKey   string
	ScopeKind ScopeKind
	ScopeID   uuid.UUID // org id (org scope) or resource id (resource scope); zero for tenant
	ScopeType string    // resource_type key when ScopeKind == ScopeResourceType
	Perms     []string  // permission keys the role grants
}

type AuditSink interface {
	AuthzDenial(ctx context.Context, a Actor, perm string, t Target, reason string)
}

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

type Condition struct {
	Attribute string          // "resource.status", "actor.relationship", "env.time_of_day"
	Op        string          // eq|neq|in|not_in|contains|within|gte|lte
	Value     json.RawMessage // comparison operand
}

type Decision struct {
	Allowed   bool
	Reason    string
	PolicyIDs []uuid.UUID
	// StepUpRequired is set when the actor would be allowed but the permission
	// demands an elevated auth factor the actor has not satisfied (roadmap S3).
	// The HTTP gate turns this into a re-authentication challenge rather than a
	// flat 403.
	StepUpRequired bool
	// StepUpChallenge names the factor/hint to advertise in the step-up
	// challenge (WWW-Authenticate's `step_up="…"` parameter) when
	// StepUpRequired is set — the permission's StepUpPolicy.Challenge, or the
	// deployment's configured default challenge for the plain `step_up: true`
	// shorthand. Empty when StepUpRequired is false.
	StepUpChallenge string
}

type Evaluator interface {
	// Evaluate returns whether actor a may exercise permission perm on target t.
	Evaluate(ctx context.Context, db database.TenantDB, a Actor, perm string, t Target) (Decision, error)
	// Filter returns the record-level constraint for listing resources of type
	// rt that a may exercise perm on.
	Filter(ctx context.Context, db database.TenantDB, a Actor, perm string, rt string) (ListFilter, error)
}

type ListFilter struct {
	All bool // true → no record-level restriction (tenant RLS still applies)
	// OrgIDs, when non-nil, restricts to resources in these orgs.
	OrgIDs []uuid.UUID
	// ResourceIDs, when non-nil, restricts to these specific resource ids
	// (e.g. relationship-derived visibility).
	ResourceIDs []uuid.UUID
}

type Options struct {
	Store         Store
	Relationships RelationshipChecker
	Registry      *Registry
	Policies      PolicyEngine
	Audit         AuditSink
	Now           func() time.Time
	// StrongFactors is the deployment-configurable default strong-factor AMR
	// set used by the `step_up: true` shorthand (a permission with no
	// StepUpPolicy). Empty/nil uses DefaultStrongFactors (mfa, otp, totp, hwk,
	// fpt, face — "sms" is EXCLUDED by default, per Decision 5: SMS-based
	// step-up is opt-in only, added by naming "sms" explicitly here). This is
	// the config surface a deployment overrides WITHOUT code changes (wired
	// via kernel.Deps.StepUpStrongFactors — see kernel/kernel.go).
	StrongFactors []string
	// DefaultChallenge is the factor/hint advertised in WWW-Authenticate for a
	// permission using the default strong-factor set (no per-permission
	// StepUpPolicy.Challenge). Empty defaults to "mfa".
	DefaultChallenge string
}

type Permission struct {
	Key        string
	Sensitive  bool
	GrantedVia string // relationship type key, or "" for none
	// StepUp requires the actor to have satisfied an elevated authentication
	// factor (MFA) for this permission: an otherwise-allowed decision becomes a
	// step-up challenge when the actor's AMR carries no strong factor (roadmap
	// S3). MFA itself is the IdP's job; this gates on the surfaced amr claim.
	// This is the persisted shorthand (permissions.step_up) — "require ANY
	// factor from the deployment's configured default strong-factor set".
	StepUp bool
	// StepUpPolicy, when non-nil, REPLACES the default-set behavior of StepUp
	// with a permission-specific requirement (e.g. "require hwk specifically").
	// It is declared by a seed's richer step_up form (kernel/seeds) and lives
	// only in this in-memory, boot-populated registry — it is NOT persisted
	// (permissions.step_up remains a plain bool; see kernel/seeds doc comment
	// on PermissionSeed.StepUpAMR for the rationale). A permission with
	// StepUpPolicy set is treated as StepUp-gated regardless of the StepUp bool.
	StepUpPolicy *StepUpPolicy
}

type PgStore struct{}

type Policy struct {
	ID         uuid.UUID
	Key        string
	Effect     PolicyEffect
	Priority   int // lower first
	Conditions []Condition
}

type PolicyEffect string

type PolicyEngine interface {
	// Matches reports whether every condition holds for the given attributes.
	Matches(conds []Condition, attrs map[string]any) (bool, error)
}

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

type RelationshipChecker interface {
	Has(ctx context.Context, db database.TenantDB, subject Actor, relType string, obj resource.Ref, at time.Time) (bool, error)
}

type ScopeKind string

type StepUpPolicy struct {
	// RequiredAMR is the set of AMR values that satisfy this permission's
	// step-up gate; the actor needs ANY ONE of them. Empty means "fall back to
	// the deployment's configured default strong-factor set" (the StepUp bool
	// shorthand's behavior).
	RequiredAMR []string
	// Challenge is the factor/hint advertised in the step-up challenge's
	// WWW-Authenticate header (e.g. `step_up="hwk"`). Empty falls back to the
	// deployment's default challenge hint.
	Challenge string
}

type Store interface {
	// ActiveAssignments returns the actor's active assignments (role perms
	// joined) at time at.
	ActiveAssignments(ctx context.Context, db database.TenantDB, a Actor, at time.Time) ([]Assignment, error)
	// OrgAncestors returns orgID and all its ancestor org ids (self-first), so
	// the evaluator can decide whether an org-scoped assignment (a grant at an
	// ancestor org) covers a target in orgID. Empty/zero orgID → empty.
	OrgAncestors(ctx context.Context, db database.TenantDB, orgID uuid.UUID) ([]uuid.UUID, error)
	// OrgSubtree returns orgID and all descendant org ids, for building list
	// filters from org-scoped assignments.
	OrgSubtree(ctx context.Context, db database.TenantDB, orgID uuid.UUID) ([]uuid.UUID, error)
	// Policies returns active policies applicable to perm on resource type rt,
	// ordered by priority ascending (evaluator applies deny-first anyway).
	Policies(ctx context.Context, db database.TenantDB, a Actor, perm, rt string) ([]Policy, error)
	// ResourceOrg returns the org id owning a resource (for org-scope checks on
	// a resource target), or zero if none/unknown.
	ResourceOrg(ctx context.Context, db database.TenantDB, ref resource.Ref) (uuid.UUID, error)
}

type Target struct {
	Scope    ScopeKind
	OrgID    uuid.UUID
	Resource resource.Ref
}