Interface AuthorizationEngine

internal/authorization/engine/engine.go:113–178

AuthorizationEngine is the SPI for a ReBAC authorization backend. All decision methods (Check, BatchCheck, ListObjects) are fail-closed at the call site: callers must treat a non-nil error as a deny and never as an allow. Identifiers follow OpenFGA conventions ("type:id", relation names, usersets "

//
// Implementations are expected to be safe for concurrent use.
type AuthorizationEngine interface {
	// Check reports whether user is related to object via relation. Optional
	// contextual tuples are evaluated for this call only and are not persisted.
	// Returns (false, err) on engine error; callers must fail closed.
	Check(ctx context.Context, user, relation, object string, ctxTuples ...ContextualTuple) (bool, error)

	// BatchCheck evaluates multiple CheckRequests. The returned slice is
	// positionally aligned with the input: result[i] answers requests[i]. An
	// error indicates a whole-batch failure; callers must fail closed for every
	// request in the batch.
	BatchCheck(ctx context.Context, requests []CheckRequest) ([]CheckResult, error)

	// ListObjects returns the IDs of objects of type objType to which user is
	// related via relation. This is the RAG/pre-filter primitive and is an
	// expensive enumeration surface — callers must paginate, cap, and
	// rate-limit. Returned IDs are fully qualified ("document:1").
	ListObjects(ctx context.Context, user, relation, objType string) ([]string, error)

	// ListUsers returns the fully qualified user IDs (e.g. "user:alice") of type
	// userType that have relation on object. It is the inverse of ListObjects:
	// "who can access this object?". This is a powerful enumeration surface that
	// reveals the access graph — callers must admin-gate, cap and audit. Returned
	// users are fully qualified ("user:alice").
	ListUsers(ctx context.Context, object, relation, userType string) ([]string, error)

	// Expand returns the OpenFGA relationship/userset tree for (relation, object)
	// rendered as a JSON string. This is the explainability/"why" primitive: it
	// shows how a relation resolves (direct assignments, usersets, computed
	// relations). It reveals the access graph and must be admin-gated.
	Expand(ctx context.Context, relation, object string) (string, error)

	// WriteTuples persists the given relationship tuples. It is additive;
	// duplicate writes may error depending on the backend.
	WriteTuples(ctx context.Context, tuples []TupleKey) error

	// DeleteTuples removes the given relationship tuples. Deleting a
	// non-existent tuple may error depending on the backend.
	DeleteTuples(ctx context.Context, tuples []TupleKey) error

	// ReadTuples returns a page of persisted tuples matching the filter, plus a
	// continuation token. It is an enumeration surface — always paginate.
	ReadTuples(ctx context.Context, filter ReadTuplesFilter) (*ReadTuplesResult, error)

	// WriteModel installs a new authorization model from its DSL form and
	// returns the backend-assigned model ID. Writing a model is powerful (a
	// single edit can re-grant broadly) and must be admin-gated, audited, and
	// staged by callers.
	WriteModel(ctx context.Context, dsl string) (string, error)

	// ReadModel returns the currently active authorization model: its
	// backend-assigned id and its DSL rendering.
	ReadModel(ctx context.Context) (id string, dsl string, err error)

	// TypeRelations returns, for every object type in the active model, the
	// relation names defined on it (type -> sorted relation names). Types with
	// no relations are omitted. It powers "list everything this subject can
	// access" enumeration. Returns ErrNoModel (wrapped) when no model has been
	// written yet.