Documentation
¶
Overview ¶
Package fga provides a fail-closed fine-grained authorization client for the kombify platform (ADR 0030). It is the Go twin of @kombify/fga (TypeScript) in kombify-Gateway/packages/fga — same API surface, same env-var contract.
Backend: managed Auth0 FGA (prod) or self-hosted OpenFGA (CI/shadow). Legacy checks resolve errors to DENY. CheckStrict preserves dependency errors for HTTP boundaries that must distinguish a definitive deny from an outage, while DeleteTuplesIdempotent provides a write-authoritative revocation path.
Self-hosted builds that have no FGA backend should use the build tag approach: in edition=selfhost the authorization decision falls back to Postgres RLS owner-checks, so the FGA wrapper is not called. Callers must guard with the appropriate edition flag before calling this package.
Usage:
fgaClient, err := fga.FromEnv()
if err != nil {
// FGA not configured — deny or fall back per edition rules.
}
allowed, err := fgaClient.CheckStrict(ctx, fga.UserPrincipal(sub), fga.CanRead, fga.DocumentObject(docID))
Index ¶
- Constants
- Variables
- func AgentClassPrincipal(class string) string
- func ChunkObject(id string) string
- func DocumentObject(id string) string
- func EntitlementObject(lookupKey string) string
- func ToolObject(id string) string
- func UserPrincipal(sub string) string
- type ClientCredentials
- type Config
- type KombifyFga
- func (f *KombifyFga) BatchCheck(ctx context.Context, user, relation string, objects []string) (map[string]bool, error)
- func (f *KombifyFga) BatchCheckObo(ctx context.Context, userSub, agentClass, relation string, objects []string) (map[string]bool, error)
- func (f *KombifyFga) Check(ctx context.Context, user, relation, object string) (bool, error)
- func (f *KombifyFga) CheckObo(ctx context.Context, userSub, agentClass, relation, object string) (bool, error)
- func (f *KombifyFga) CheckStrict(ctx context.Context, user, relation, object string) (bool, error)
- func (f *KombifyFga) DeleteTuples(ctx context.Context, tuples []openfga.TupleKeyWithoutCondition) error
- func (f *KombifyFga) DeleteTuplesIdempotent(ctx context.Context, tuples []openfga.TupleKeyWithoutCondition) error
- func (f *KombifyFga) WriteTuples(ctx context.Context, tuples []openfga.TupleKey) error
Constants ¶
const ( TypeUser = "user" TypeAgentClass = "agent_class" TypeOrg = "org" TypeTeam = "team" TypeTenant = "tenant" TypeDocument = "document" TypeChunk = "chunk" TypeSurface = "surface" TypeServer = "server" TypeTool = "tool" TypeEntitlement = "entitlement" )
Type constants match the FGA model types in kombify-Gateway/packages/fga/model.fga.
const ( CanRead = "can_read" CanCall = "can_call" Viewer = "viewer" Caller = "caller" Member = "member" ExcludedClass = "excluded_class" Accessor = "accessor" Grantee = "grantee" Has = "has" )
Relation constants match the FGA model relations.
Variables ¶
var ErrNotConfigured = fmt.Errorf("fga: not configured (AUTH0_FGA_STORE_ID / FGA_STORE_ID missing)")
ErrNotConfigured is returned by FromEnv when required env vars are absent.
Functions ¶
func AgentClassPrincipal ¶
func ChunkObject ¶
func DocumentObject ¶
func EntitlementObject ¶
func ToolObject ¶
func UserPrincipal ¶
Types ¶
type ClientCredentials ¶
type ClientCredentials struct {
ClientID string
ClientSecret string
APITokenIssuer string
APIAudience string
}
ClientCredentials holds OAuth2 client-credentials for managed Auth0 FGA.
type Config ¶
type Config struct {
APIURL string
StoreID string
AuthorizationModelID string
// When set, the client uses Auth0 FGA client-credentials (managed prod).
// When nil, it connects to a local/self-hosted OpenFGA instance without auth.
Credentials *ClientCredentials
}
Config holds the FGA backend connection parameters.
type KombifyFga ¶
type KombifyFga struct {
// contains filtered or unexported fields
}
KombifyFga is the FGA client. Legacy Check methods collapse dependency errors to a false decision; strict methods preserve errors for application policy.
func FromConfig ¶
func FromConfig(cfg *Config) (*KombifyFga, error)
FromConfig builds a KombifyFga client from an explicit Config.
func FromEnv ¶
func FromEnv() (*KombifyFga, error)
FromEnv builds a KombifyFga client from environment variables. Supports both the the configured secret source ADR names (AUTH0_FGA_*) and the OpenFGA standard names (FGA_*) — mirrors fgaConfigFromEnv in @kombify/fga. Returns ErrNotConfigured when the mandatory fields are absent; callers must treat this as a DENY.
func (*KombifyFga) BatchCheck ¶
func (f *KombifyFga) BatchCheck(ctx context.Context, user, relation string, objects []string) (map[string]bool, error)
BatchCheck checks one principal against many objects. Returns a map keyed by object → allowed. Uses individual Check calls since ClientBatchCheck is primarily correlation-id based. FAIL-CLOSED: any error → false for that object.
func (*KombifyFga) BatchCheckObo ¶
func (f *KombifyFga) BatchCheckObo(ctx context.Context, userSub, agentClass, relation string, objects []string) (map[string]bool, error)
BatchCheckObo performs OBO batch check. An object is allowed only if BOTH principals are allowed (intersection). FAIL-CLOSED on any error.
func (*KombifyFga) Check ¶
Check performs a single relationship check. It retains the original fail-closed compatibility contract: any strict-check error becomes a false decision with no error. New application boundaries should call CheckStrict.
func (*KombifyFga) CheckObo ¶
func (f *KombifyFga) CheckObo(ctx context.Context, userSub, agentClass, relation, object string) (bool, error)
CheckObo performs an agent-on-behalf-of check: the agent is authorized only when BOTH the user principal AND the agent-class principal have the relation (intersection, not union). FAIL-CLOSED on any error.
func (*KombifyFga) CheckStrict ¶
CheckStrict performs one higher-consistency relationship check and preserves backend/transport failures. Higher consistency is intentional at an authorization boundary: a recently revoked tuple must not be served from the latency-optimized cache and mistaken for current authority.
func (*KombifyFga) DeleteTuples ¶
func (f *KombifyFga) DeleteTuples(ctx context.Context, tuples []openfga.TupleKeyWithoutCondition) error
DeleteTuples removes FGA relationship tuples.
func (*KombifyFga) DeleteTuplesIdempotent ¶
func (f *KombifyFga) DeleteTuplesIdempotent(ctx context.Context, tuples []openfga.TupleKeyWithoutCondition) error
DeleteTuplesIdempotent removes relationship tuples with provider-native OnMissingDeletes=IGNORE semantics. Success is therefore an authoritative write result even when the tuple was already absent; consumers must not use a potentially stale read as an absence receipt.
func (*KombifyFga) WriteTuples ¶
WriteTuples writes FGA relationship tuples (for use by the entitlement broker).
Source Files