principal

type AuthAttempt struct {
	Subject Ref
	Actors  Chain

	AppID id.AppID
	EnvID id.EnvironmentID
	OrgID id.OrgID

	// CredentialKind is how the caller authenticated: "api_key",
	// "token_exchange" or "jwt".
	CredentialKind string
	// CredentialID identifies the specific credential, so a verdict can be
	// cached against it and a compromised one can be traced.
	CredentialID string

	IPAddress string
	UserAgent string

	// Ephemeral is true when the subject was minted by another principal
	// rather than registered.
	Ephemeral bool

	At time.Time
}

type Chain []Ref

type Delegation struct {
	ID    id.DelegationID `json:"id"`
	AppID id.AppID        `json:"app_id"`
	OrgID id.OrgID        `json:"org_id,omitempty"`

	Actor   Ref `json:"actor"`
	Subject Ref `json:"subject"`

	GrantKind GrantKind `json:"grant_kind"`
	// Scopes narrows what the actor may do while acting. An empty list places
	// no restriction of its own, leaving the actor's own scopes as the only
	// limit.
	Scopes []string `json:"scopes,omitempty"`
	// GrantedBy is who consented. For a delegation that is normally the
	// subject; for an impersonation it is the admin who initiated it.
	GrantedBy Ref `json:"granted_by"`

	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
}

type DelegationQuery struct {
	AppID      id.AppID
	OrgID      id.OrgID
	Actor      *Ref
	Subject    *Ref
	GrantKind  GrantKind
	ActiveOnly bool
	ActiveAsOf time.Time
	Limit      int
}

type GrantKind string

type Kind string

type Principal struct {
	Ref

	AppID  id.AppID
	OrgID  id.OrgID
	EnvID  id.EnvironmentID
	Name   string
	Scopes []string
	Roles  []string

	// Owner is the principal answerable for this one. Nil for users, who are
	// answerable for themselves.
	Owner *Ref
	// Parent is the registered principal that minted this one. Set only on
	// ephemeral children.
	Parent *Ref
	// ExpiresAt is a hard cutoff. Nil means durable.
	ExpiresAt *time.Time
	Disabled  bool
}

type Query struct {
	AppID      id.AppID
	Kind       Kind
	OwnerUser  *id.UserID
	Parent     *Ref
	ActiveOnly bool
	ActiveAsOf time.Time
	Limit      int
}

type Ref struct {
	Kind Kind   `json:"kind"`
	ID   string `json:"id"`
}

type Store interface {
	// GetPrincipal resolves any principal by ref. Users are assembled from
	// the user table; every other kind comes from the service accounts table.
	GetPrincipal(ctx context.Context, ref Ref) (*Principal, error)
	// ListPrincipals returns principals matching q.
	ListPrincipals(ctx context.Context, q *Query) ([]*Principal, error)

	// CreateDelegation stores a new grant.
	CreateDelegation(ctx context.Context, d *Delegation) error
	// GetDelegation returns a grant by ID.
	GetDelegation(ctx context.Context, delID id.DelegationID) (*Delegation, error)
	// FindActiveDelegation returns the live grant letting actor act for
	// subject under grantKind, or ErrNotFound.
	FindActiveDelegation(ctx context.Context, appID id.AppID, actor, subject Ref, grantKind GrantKind) (*Delegation, error)
	// ListDelegations returns grants matching q.
	ListDelegations(ctx context.Context, q *DelegationQuery) ([]*Delegation, error)
	// RevokeDelegation marks a grant revoked at the given time. Revoking an
	// already-revoked grant is not an error.
	RevokeDelegation(ctx context.Context, delID id.DelegationID, at time.Time) error
}