cedar

type Capability struct {
	// Name is the capability's short id (e.g. "kv", "invoke", "s3", "egress") — for diagnostics/dedup.
	// Unique across the registry.
	Name string
	// Actions are the Cedar actions this capability authorizes (e.g. auth.ActionKVRead, ActionKVWrite).
	// Unique across the registry (no two capabilities share an action).
	Actions []auth.Action
	// EmitsEntityType is the primary Cedar entity type this capability materializes as a resource (e.g.
	// entityTypeKVTable). Used ONLY for schema-vocabulary assembly (KnownEntityType) — NOT a dispatch key
	// (an EntityRef.Type v1.Kind never equals the Cedar entity type: KindKVStore→KVTable, KindBucket→
	// BlobPrefix). Resource dispatch is by the Resource func's ok, below.
	EmitsEntityType cedartypes.EntityType
	// SupportingEntityTypes are the additional Cedar entity types this capability contributes to the
	// schema vocabulary beyond its primary EmitsEntityType — the resource's parent (KVStore for kv,
	// Bucket for s3) and any alternate principal type it admits (S3Identity for s3). A Policy may scope
	// on these (`resource in KVStore::"…"`, `principal == S3Identity::"…"`), so KnownEntityType must
	// accept them; they are assembled from the registry exactly like EmitsEntityType (never hand-listed).
	SupportingEntityTypes []cedartypes.EntityType
	// Resource materializes the resource entity (UID + parents + owner attr) for a request whose resource
	// this capability owns. ok==false ⇒ not ours (try the next capability) — this ok is the SOLE resource-
	// dispatch mechanism. A dangling resource still returns ok==true with bare entities (evaluable,
	// default-deny). nil ⇒ the capability owns no resource shape (Policy-only over an existing entity).
	Resource func(ctx context.Context, r MetaReader, resource auth.EntityRef) (em cedartypes.EntityMap, ok bool, err error)
	// PrincipalBinding declares this capability's binding-as-grant attribute on the principal: Attr is the
	// principal attribute name (e.g. "kvBindings"); Bind materializes its members from a resolved
	// principal object (see PrincipalSource). The provider sets Attr whenever Bind returns a non-nil slice
	// (possibly empty), matching today's EntitiesFor (a Function always carries links/kvBindings/blobBindings;
	// the built-ins also `has`-guard, so empty ≡ absent). A Bind that returns nil for a source type
	// contributes nothing (attr absent) — e.g. kv/invoke for a CatalogService. Zero value ⇒ no binding.
	PrincipalBinding PrincipalBinding
	// Builtin is this capability's built-in permit policy text (the .cedar granting the capability when
	// principal.<attr>.contains(resource)); "" ⇒ no built-in (Policy-only).
	Builtin string
}

type Deps struct {
	// Entities resolves the request-relevant Cedar entities per call (principal + resource + parents).
	Entities EntityProvider
	// Policies supplies the user Policy resources (compiled + cached with the built-ins).
	Policies PolicySource
	// Builtins is the always-on built-in Cedar policy text (a Registry's Builtins()) compiled into the
	// PolicySet with the user Policies. Empty ⇒ the default registry's built-ins — so the compose root can
	// supply a variant built-in set (e.g. funcdctl dev's relaxed S3 writes) without a package global.
	Builtins string
	// Logger is the driver's logger; nil ⇒ slog.Default().
	Logger *slog.Logger
}

type EntityProvider interface {
	EntitiesFor(ctx context.Context, principal, resource auth.EntityRef) (cedartypes.EntityMap, error)
}

type MetaReader interface {
	Get(ctx context.Context, gvk v1.GroupVersionKind, ns v1.NamespaceName, name v1.ObjectName) (v1.Object, error)
}

type PolicySource interface {
	// Policies returns all Policy resources and an opaque revision; the driver recompiles only when
	// the revision changes (cheap cache invalidation without diffing policy text).
	Policies(ctx context.Context) (policies []v1.Policy, revision string, err error)
}

type PrincipalBinding struct {
	// Attr is the Cedar principal attribute (e.g. "kvBindings", "links", "blobBindings").
	Attr string
	// Bind materializes the attribute's Set members from a resolved principal object. src is whatever a
	// PrincipalSource resolved (a *v1.Function or a *v1.CatalogService); a capability that doesn't apply to
	// that source type returns nil (e.g. kv/invoke return nil for a CatalogService — providers have no
	// links/kv). ns is the principal namespace (for building same-namespace resource UIDs).
	Bind func(ns v1.NamespaceName, src PrincipalObject) []cedartypes.EntityUID
}

type PrincipalObject = v1.PrincipalObject

type PrincipalSource func(ctx context.Context, r MetaReader, p auth.EntityRef) (obj PrincipalObject, ok bool, err error)

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

type RoleResolver interface {
	Actions(ctx context.Context, ref v1.RoleRef, ns v1.NamespaceName) ([]string, bool)
}

type WriterGrant struct {
	Principal cedartypes.EntityUID
	Scope     v1.ScopeRef
}

type WriterLister interface {
	BlobWriters(ctx context.Context, ns v1.NamespaceName, bucket, prefix string) []cedartypes.EntityUID
	KVWriters(ctx context.Context, ns v1.NamespaceName, store, table string) []cedartypes.EntityUID
}