schema

type AuthzModel ¶

type AuthzModel struct {
	ID               int64
	ObjectType       string  // Object type this rule applies to
	Relation         string  // Relation this rule defines
	SubjectType      *string // Allowed subject type (for direct rules)
	ImpliedBy        *string // Implying relation (for role hierarchy)
	ParentRelation   *string // Parent relation to check (for inheritance)
	ExcludedRelation *string // Relation to exclude (for "but not" rules)
	SubjectWildcard  *bool   // Whether wildcard subjects are allowed for SubjectType
	// Excluded parent relation for tuple-to-userset exclusions.
	ExcludedParentRelation *string // Parent relation to exclude (for "but not rel from parent")
	ExcludedParentType     *string // Linking relation for the excluded parent relation
	// New fields for userset references and intersection support
	SubjectRelation       *string // For userset refs [type#relation]: the relation part
	RuleGroupID           *int64  // Groups rules that form an intersection
	RuleGroupMode         *string // 'intersection' for AND, 'union' or NULL for OR
	CheckRelation         *string // For intersection: which relation to check
	CheckExcludedRelation *string // For intersection: exclusion on check_relation (e.g., "editor but not owner")
	CheckParentRelation   *string // For intersection: parent relation to check (tuple-to-userset)
	CheckParentType       *string // For intersection: linking relation on current object
}

AuthzModel represents an entry in the melange_model table. Each row defines one authorization rule that check_permission evaluates.

The table stores the flattened authorization model, precomputing transitive closures and normalizing rules for efficient query execution.

Rule types:

• Direct: SubjectType is set, others NULL (user can have relation)
• Implied: ImpliedBy is set (having one relation grants another)
• Parent: ParentRelation and SubjectType set (inherit from parent object)
• Exclusive: ExcludedRelation set (permission denied if exclusion holds)
• Userset: SubjectType and SubjectRelation set (e.g., [group#member])
• Intersection: RuleGroupID and RuleGroupMode set (AND semantics)

func ToAuthzModels(types []TypeDefinition) []AuthzModel

type ClosureRow ¶

type ClosureRow struct {
	ObjectType         string
	Relation           string
	SatisfyingRelation string
	ViaPath            []string // For debugging: path from relation to satisfying_relation
}

ClosureRow represents a row in the melange_relation_closure table. The closure table is a critical optimization that precomputes transitive implied-by relationships at schema load time, eliminating the need for recursive function calls during permission checks.

Each row indicates that having satisfying_relation grants the relation on objects of object_type. For example, in a role hierarchy where owner -> admin -> member:

• {object_type: "repo", relation: "member", satisfying_relation: "owner"}
• {object_type: "repo", relation: "member", satisfying_relation: "admin"}
• {object_type: "repo", relation: "member", satisfying_relation: "member"}

This allows check_permission to evaluate "does user have member?" with a simple JOIN rather than recursive traversal: just check if they have ANY of the satisfying relations.

func ComputeRelationClosure(types []TypeDefinition) []ClosureRow

type Execer ¶

type Execer interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

Execer is the minimal interface needed for schema migration operations. Implemented by *sql.DB, *sql.Tx, and *sql.Conn.

type GenerateConfig ¶

type GenerateConfig struct {
	// Package name for generated code. Default: "authz"
	Package string

	// RelationPrefixFilter is a prefix filter for relation names.
	// Only relations with this prefix will have constants generated.
	// If empty, all relations will be generated.
	//
	// Example: "can_" generates only permission relations, omitting roles.
	RelationPrefixFilter string

	// IDType specifies the type to use for object IDs.
	// Default: "string"
	// The type must implement fmt.Stringer or be safely convertible to string.
	//
	// Common values: "string", "int64", "uuid.UUID"
	// The generated code uses fmt.Sprint(id) for conversion.
	IDType string
}

GenerateConfig configures code generation. The generator produces Go code with type-safe constants for object types and relations defined in the FGA schema.

func DefaultGenerateConfig() *GenerateConfig

type IntersectionGroup ¶

type IntersectionGroup struct {
	Relations       []string              // Relations that must all be satisfied (AND)
	ParentRelations []ParentRelationCheck // Parent inheritance checks (tuple-to-userset)
	Exclusions      map[string][]string   // Per-relation exclusions: relation -> list of excluded relations
}

IntersectionGroup represents a group of relations that must ALL be satisfied. For "viewer: writer and editor", the group would be ["writer", "editor"]. For "viewer: writer and (editor but not owner)", the group would be ["writer", "editor"] with Exclusions["editor"] = ["owner"].

type Migrator ¶

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

Migrator handles loading authorization schemas into PostgreSQL. The migrator is idempotent - safe to run on every application startup.

The migration process:

1. Creates melange_model table (if not exists)
2. Creates/replaces check_permission and list_accessible_* functions
3. Loads pre-parsed authorization rules into the database

Usage with Tooling Module ¶

For most use cases, use the tooling module's convenience functions which handle parsing and migration in one step:

import "github.com/pthm/melange/tooling"
err := tooling.Migrate(ctx, db, "schemas")

Use the core Migrator directly when you have pre-parsed TypeDefinitions or need fine-grained control (DDL-only, status checks, etc.):

types, _ := tooling.ParseSchema("schemas/schema.fga")
migrator := schema.NewMigrator(db, "schemas")
err := migrator.MigrateWithTypes(ctx, types)

This separation keeps the core melange package free of OpenFGA dependencies.

func NewMigrator(db Execer, schemasDir string) *Migrator

func (m *Migrator) ApplyDDL(ctx context.Context) error

func (m *Migrator) GetStatus(ctx context.Context) (*Status, error)

func (m *Migrator) HasSchema() bool

func (m *Migrator) MigrateWithTypes(ctx context.Context, types []TypeDefinition) error

func (m *Migrator) SchemaPath() string

type ParentRelationCheck ¶

type ParentRelationCheck struct {
	Relation   string // Relation to check on the parent object (e.g., "viewer")
	ParentType string // Linking relation on the current object (e.g., "parent")
}

ParentRelationCheck represents a tuple-to-userset check in an intersection group. For "viewer: writer and (viewer from parent)", this captures the parent relation.

type RelationDefinition ¶

type RelationDefinition struct {
	Name              string   // Relation name: "owner", "can_read", etc.
	SubjectTypes      []string // Direct subject types: ["user"], ["organization"] (legacy)
	ImpliedBy         []string // Relations that imply this one: ["owner", "admin"]
	ParentRelation    string   // For inheritance: "can_read from org" → "can_read" (legacy)
	ParentType        string   // The relation linking to parent: "org", "repo" (legacy)
	ParentRelations   []ParentRelationCheck
	ExcludedRelation  string   // For exclusions: "can_read but not author" -> "author" (deprecated, use ExcludedRelations)
	ExcludedRelations []string // For nested exclusions: "(a but not b) but not c" -> ["b", "c"]
	// ExcludedParentRelations captures tuple-to-userset exclusions like "but not viewer from parent".
	ExcludedParentRelations []ParentRelationCheck
	// ExcludedIntersectionGroups captures exclusions that require ALL relations in a group.
	// For "viewer: writer but not (editor and owner)", this is [[editor, owner]].
	ExcludedIntersectionGroups []IntersectionGroup
	// SubjectTypeRefs provides detailed subject type info including userset relations.
	// For [user, group#member], this would contain:
	//   - {Type: "user", Relation: ""}
	//   - {Type: "group", Relation: "member"}
	SubjectTypeRefs []SubjectTypeRef
	// IntersectionGroups contains groups of relations that must ALL be satisfied.
	// Each group is an AND (intersection), multiple groups are OR'd together.
	// For "viewer: writer and editor", IntersectionGroups = [["writer", "editor"]]
	// For "viewer: (a and b) or (c and d)", IntersectionGroups = [["a","b"], ["c","d"]]
	IntersectionGroups []IntersectionGroup
}

RelationDefinition represents a parsed relation. Relations describe who can have what relationship with an object.

A relation can be:

• Direct: explicitly granted via tuples (SubjectTypes)
• Implied: granted by having another relation (ImpliedBy)
• Inherited: derived from a parent object (ParentRelation, ParentType)
• Exclusive: granted except for excluded subjects (ExcludedRelation)
• Userset: granted via group membership (SubjectTypeRefs with Relation set)
• Intersection: granted if ALL relations in a group are satisfied

type Status ¶

type Status struct {
	// SchemaExists indicates if the schema.fga file exists on disk.
	SchemaExists bool

	// ModelCount is the number of rows in the melange_model table.
	// Zero means the schema hasn't been loaded (run `melange migrate`).
	ModelCount int64

	// ClosureCount is the number of rows in the melange_relation_closure table.
	// This table stores precomputed transitive implied-by relationships.
	ClosureCount int64

	// IndexCount is the number of melange-related indexes found.
	// Expected to be at least 5 after a successful migration.
	IndexCount int

	// TuplesExists indicates if the melange_tuples relation exists (view, table, or materialized view).
	// This must be created by the user to map their domain tables.
	TuplesExists bool
}

Status represents the current migration state. Use GetStatus to check if the authorization system is properly configured.

type SubjectTypeRef ¶

type SubjectTypeRef struct {
	Type     string // Subject type: "user", "group", etc.
	Relation string // For userset refs: the relation (e.g., "member" in [group#member])
	Wildcard bool   // True if this is a wildcard reference (user:*)
}

SubjectTypeRef represents a subject type reference in a relation definition. For userset references like [group#member], Type is "group" and Relation is "member". For direct references like [user], Type is "user" and Relation is empty.

type TypeDefinition ¶

type TypeDefinition struct {
	Name      string
	Relations []RelationDefinition
}

TypeDefinition represents a parsed type from an .fga file. Each type definition describes an object type (user, repository, etc.) and the relations that can exist on objects of that type.

type UsersetRule ¶

type UsersetRule struct {
	ObjectType                string
	Relation                  string
	TupleRelation             string
	SubjectType               string
	SubjectRelation           string
	SubjectRelationSatisfying string
}

UsersetRule represents a precomputed userset rule with relation closure applied. Userset rules handle permissions granted via group membership, expressed in OpenFGA as [group#member]. Unlike direct subject types where the tuple directly grants permission, usersets require checking if the subject has the specified relation on the group object.

Each row means: a tuple with tuple_relation on object_type can satisfy relation when the tuple subject is subject_type#subject_relation.

The rules are precomputed by expanding userset references through the relation closure table. This allows SQL to resolve userset permissions efficiently without nested subqueries for each implied relation.

Example: For "viewer: [group#member]" where admin->member, the rules include:

• {relation: "viewer", tuple_relation: "viewer", subject_type: "group", subject_relation: "member", subject_relation_satisfying: "member"}
• {relation: "viewer", tuple_relation: "viewer", subject_type: "group", subject_relation: "member", subject_relation_satisfying: "admin"}

This enables check_permission to match tuples where the subject has either member or admin on the group, without recursive relation resolution at query time.

func ToUsersetRules(types []TypeDefinition, closureRows []ClosureRow) []UsersetRule