authorization

package
v0.102.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 12, 2026 License: MIT Imports: 8 Imported by: 3

Documentation

Overview

Package authorization defines the portable TugQL authorization result wire contract.

Index

Constants

View Source 
const (
	// CodeAccessDenied aliases access.CodeAccessDenied, the blocker code ACCESS_DENIED.
	CodeAccessDenied = access.CodeAccessDenied
	// CodeRuleDenied aliases access.CodeRuleDenied, the blocker code ACL_RULE_DENIED.
	CodeRuleDenied = access.CodeRuleDenied
	// CodeNoMatch aliases access.CodeNoMatch, the blocker code ACL_NO_MATCH.
	CodeNoMatch = access.CodeNoMatch
	// CodeRowPredicateFailed aliases access.CodeRowPredicateFailed, the blocker code ACL_ROW_PREDICATE_FAILED.
	CodeRowPredicateFailed = access.CodeRowPredicateFailed
	// CodePostImageFailed aliases access.CodePostImageFailed, the blocker code ACL_POST_IMAGE_FAILED.
	CodePostImageFailed = access.CodePostImageFailed
	// CodeColumnDenied aliases access.CodeColumnDenied, the blocker code ACL_COLUMN_DENIED.
	CodeColumnDenied = access.CodeColumnDenied
	// CodeEvaluationFailed aliases access.CodeEvaluationFailed, the blocker code ACL_EVALUATION_FAILED.
	CodeEvaluationFailed = access.CodeEvaluationFailed
	// CodeConfigurationInvalid aliases access.CodeConfigurationInvalid, the blocker code ACL_CONFIGURATION_INVALID.
	CodeConfigurationInvalid = access.CodeConfigurationInvalid
	// CodeSourceUnavailable aliases access.CodeSourceUnavailable, the blocker code ACL_SOURCE_UNAVAILABLE.
	CodeSourceUnavailable = access.CodeSourceUnavailable
	// CodeEnforcementUnsupported aliases access.CodeEnforcementUnsupported, the blocker code ACL_ENFORCEMENT_UNSUPPORTED.
	CodeEnforcementUnsupported = access.CodeEnforcementUnsupported
	// CodePrincipalUnresolved aliases access.CodePrincipalUnresolved, the blocker code ACL_PRINCIPAL_UNRESOLVED.
	CodePrincipalUnresolved = access.CodePrincipalUnresolved
	// CodeCapabilityDenied aliases access.CodeCapabilityDenied, the blocker code ACL_CAPABILITY_DENIED.
	CodeCapabilityDenied = access.CodeCapabilityDenied
	// CodeExecutionClassDenied aliases access.CodeExecutionClassDenied, the blocker code ACL_EXECUTION_CLASS_DENIED.
	CodeExecutionClassDenied = access.CodeExecutionClassDenied
	// CodeCallableDenied aliases access.CodeCallableDenied, the blocker code ACL_CALLABLE_DENIED.
	CodeCallableDenied = access.CodeCallableDenied
	// CodeCollectionDenied aliases access.CodeCollectionDenied, the blocker code ACL_COLLECTION_DENIED.
	CodeCollectionDenied = access.CodeCollectionDenied
)
View Source 
const APIVersion = "tugql.org/authorization/v1"

APIVersion is the authorization result apiVersion, tugql.org/authorization/v1.

Variables

This section is empty.

Functions

func MarshalResult 

func MarshalResult(result Result) ([]byte, error)

MarshalResult encodes result as JSON after Validate succeeds.

Types

type AuthorizationResult 

type AuthorizationResult = Result

AuthorizationResult is an alias of Result.

type BindingRef 

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

BindingRef identifies a binding by Kind and ID.

type Blocker 

type Blocker struct {
	OperationID    string         `json:"operationId"`
	Code           ReasonCode     `json:"code"`
	Scope          Scope          `json:"scope"`
	Resource       *Resource      `json:"resource,omitempty"`
	LayerID        string         `json:"layerId,omitempty"`
	PolicyRef      *PolicyRef     `json:"policyRef,omitempty"`
	Slot           string         `json:"slot,omitempty"`
	Columns        [][]string     `json:"columns,omitempty"`
	Retryable      *bool          `json:"retryable,omitempty"`
	ExecutionClass ExecutionClass `json:"executionClass,omitempty"`
	Callable       *Callable      `json:"callable,omitempty"`
}

Blocker records a ReasonCode on an operation. OperationID, Code, and Scope are required, and Slot is where, check, or fields when set. An allowed result cannot contain blockers.

type Callable 

type Callable struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
}

Callable names a stored procedure by Namespace and Name.

type Coverage 

type Coverage struct {
	Evaluation  EvaluationCompleteness `json:"evaluation"`
	Disclosure  DisclosureCompleteness `json:"disclosure"`
	Truncated   bool                   `json:"truncated"`
	Unevaluated []Unevaluated          `json:"unevaluated"`
}

Coverage reports evaluation and disclosure for a Result. Evaluation is complete or partial, Disclosure is full or redacted, and Unevaluated must be an array.

type DisclosureCompleteness 

type DisclosureCompleteness string

DisclosureCompleteness is the coverage disclosure discriminator. Validate accepts full and redacted. 

const (
	// DisclosureFull is the disclosure value "full".
	DisclosureFull DisclosureCompleteness = "full"
	// DisclosureRedacted is the disclosure value "redacted".
	DisclosureRedacted DisclosureCompleteness = "redacted"
)

type EvaluationCompleteness 

type EvaluationCompleteness string

EvaluationCompleteness is the coverage evaluation discriminator. Validate accepts complete and partial. 

const (
	// EvaluationComplete is the evaluation value "complete".
	// Allowed is true exactly when the result is allow and evaluation is complete.
	EvaluationComplete EvaluationCompleteness = "complete"
	// EvaluationPartial is the evaluation value "partial".
	EvaluationPartial EvaluationCompleteness = "partial"
)

type ExecutionClass 

type ExecutionClass string

ExecutionClass names how an operation runs. Validate accepts tugql, native_sql, native_graphql, and stored_procedure. 

const (
	// ExecutionTugQL is the execution class "tugql".
	ExecutionTugQL ExecutionClass = "tugql"
	// ExecutionNativeSQL is the execution class "native_sql".
	ExecutionNativeSQL ExecutionClass = "native_sql"
	// ExecutionNativeGraphQL is the execution class "native_graphql".
	ExecutionNativeGraphQL ExecutionClass = "native_graphql"
	// ExecutionStoredProcedure is the execution class "stored_procedure".
	// An operation sets Callable exactly when its class is ExecutionStoredProcedure.
	ExecutionStoredProcedure ExecutionClass = "stored_procedure"
)

type Layer 

type Layer struct {
	LayerID        string          `json:"layerId"`
	Source         Source          `json:"source"`
	ACLState       string          `json:"aclState"`
	Result         Outcome         `json:"result"`
	PolicyRevision string          `json:"policyRevision,omitempty"`
	Decisions      []LayerDecision `json:"decisions"`
}

Layer is one authorization source in a Result. ACLState is enabled, disabled, or unavailable, and Decisions must be an array.

type LayerDecision 

type LayerDecision struct {
	OperationID    string       `json:"operationId"`
	Result         Outcome      `json:"result"`
	PolicyRef      *PolicyRef   `json:"policyRef,omitempty"`
	Scope          Scope        `json:"scope"`
	RuleRefs       []string     `json:"ruleRefs,omitempty"`
	BindingRefs    []BindingRef `json:"bindingRefs,omitempty"`
	RestrictionIDs []string     `json:"restrictionIds"`
}

LayerDecision is one operation decision inside a Layer. It records the outcome, scope, optional policy, rule, and binding references, and restriction ids.

type Mode 

type Mode string

Mode is the authorization mode. Validate accepts plan, inspect, sample, and execution. 

const (
	// ModePlan is the mode value "plan".
	ModePlan Mode = "plan"
	// ModeInspect is the mode value "inspect".
	ModeInspect Mode = "inspect"
	// ModeSample is the mode value "sample".
	// Sample mode requires scope "sample" and a Sample summary.
	ModeSample Mode = "sample"
	// ModeExecution is the mode value "execution".
	ModeExecution Mode = "execution"
)

type OperationRef 

type OperationRef struct {
	ID                 string `json:"id"`
	RequestOperationID string `json:"requestOperationId"`
}

OperationRef identifies an operation by ID and RequestOperationID.

type OperationResult 

type OperationResult struct {
	ID                 string         `json:"id"`
	RequestOperationID string         `json:"requestOperationId"`
	Action             string         `json:"action"`
	Resource           Resource       `json:"resource"`
	Result             Outcome        `json:"result"`
	RestrictionIDs     []string       `json:"restrictionIds"`
	AllOf              []string       `json:"allOf"`
	ExecutionClass     ExecutionClass `json:"executionClass"`
	Callable           *Callable      `json:"callable,omitempty"`
}

OperationResult is one operation inside a Result. RestrictionIDs and AllOf must contain the same ids. Callable is present exactly when ExecutionClass is ExecutionStoredProcedure.

type Outcome 

type Outcome string

Outcome is an authorization result discriminator. Validate accepts allow, conditional, deny, and indeterminate. 

const (
	// OutcomeAllow is the outcome value "allow".
	OutcomeAllow Outcome = "allow"
	// OutcomeConditional is the outcome value "conditional".
	OutcomeConditional Outcome = "conditional"
	// OutcomeDeny is the outcome value "deny".
	OutcomeDeny Outcome = "deny"
	// OutcomeIndeterminate is the outcome value "indeterminate".
	OutcomeIndeterminate Outcome = "indeterminate"
)

type PolicyRef 

type PolicyRef struct {
	OwnerID    string `json:"ownerId"`
	DatabaseID string `json:"databaseId"`
	PolicyID   string `json:"policyId"`
	Revision   string `json:"revision"`
	RuleID     string `json:"ruleId,omitempty"`
}

PolicyRef identifies a policy by owner, database, policy id, and revision. RuleID is optional.

type ReasonCode 

type ReasonCode = access.ReasonCode

ReasonCode is a blocker code. It aliases access.ReasonCode.

type Resource 

type Resource struct {
	DatabaseID string     `json:"databaseId"`
	Path       string     `json:"path"`
	Table      string     `json:"table,omitempty"`
	RowID      string     `json:"rowId,omitempty"`
	Columns    [][]string `json:"columns,omitempty"`
}

Resource identifies a database object by DatabaseID and Path. Table, RowID, and Columns are optional, and each column path must be unique.

type Restriction 

type Restriction struct {
	ID             string                    `json:"id"`
	OperationID    string                    `json:"operationId"`
	LayerID        string                    `json:"layerId,omitempty"`
	PolicyRef      *PolicyRef                `json:"policyRef,omitempty"`
	Enforced       bool                      `json:"enforced"`
	Representation string                    `json:"representation"`
	Kind           string                    `json:"kind"`
	Expression     *access.DocumentCondition `json:"expression,omitempty"`
	Fields         []string                  `json:"fields,omitempty"`
	OmissionReason string                    `json:"omissionReason,omitempty"`
	Mask           *access.Mask              `json:"mask,omitempty"`
}

Restriction is a constraint attached to an operation. Representation is expression, fields, reference, or mask, and the other fields must match it. An allowed result cannot include a restriction with Enforced set to false.

type Result 

type Result struct {
	APIVersion   string            `json:"apiVersion"`
	RequestID    string            `json:"requestId"`
	Mode         Mode              `json:"mode"`
	Scope        Scope             `json:"scope"`
	Result       Outcome           `json:"result"`
	Allowed      bool              `json:"allowed"`
	Hypothetical bool              `json:"hypothetical"`
	Operations   []OperationResult `json:"operations"`
	Layers       []Layer           `json:"layers"`
	Blockers     []Blocker         `json:"blockers"`
	Coverage     Coverage          `json:"coverage"`
	Restrictions []Restriction     `json:"restrictions"`
	Sample       *Sample           `json:"sample,omitempty"`
}

Result is one portable authorization result. ParseResult rejects duplicate keys, missing required fields, and unknown fields. Validate requires apiVersion APIVersion and consistent mode, scope, outcome, and coverage.

func DecodeResultCompatible 

func DecodeResultCompatible(data []byte) (Result, error)

DecodeResultCompatible decodes returned results while preserving unknown future blocker codes. All other frozen-v1 validation remains strict, and an unknown blocker can never coexist with an allowed result.

func ParseResult 

func ParseResult(data []byte) (Result, error)

ParseResult decodes one frozen authorization result. It rejects duplicate JSON keys, missing required fields, unknown fields, and any document that fails Validate.

func (Result) Validate 

func (result Result) Validate() error

Validate checks result against the frozen authorization contract, including known blocker codes.

type Sample 

type Sample struct {
	RequestedLimit      int           `json:"requestedLimit"`
	EvaluatedCount      int           `json:"evaluatedCount"`
	Selection           string        `json:"selection"`
	Order               []SampleOrder `json:"order"`
	Exhaustive          bool          `json:"exhaustive"`
	TemplateOperationID string        `json:"templateOperationId"`
	SelectionResource   Resource      `json:"selectionResource"`
}

Sample is required when Mode is ModeSample and forbidden otherwise. Selection must be readable_candidates, Exhaustive must be false, and RequestedLimit is from 1 to 100. EvaluatedCount cannot exceed RequestedLimit, and Order has from 1 to 32 keys.

type SampleOrder 

type SampleOrder struct {
	Field     []string `json:"field"`
	Direction string   `json:"direction"`
}

SampleOrder is one sort key in a Sample. Direction is asc or desc.

type Scope 

type Scope string

Scope names what a result, decision, or blocker applies to. A Result scope is request or sample. Decisions and blockers use database, table, row, column, operation, principal, or configuration. 

const (
	// ScopeRequest is the scope value "request".
	// A non-sample result requires it.
	ScopeRequest Scope = "request"
	// ScopeSample is the scope value "sample".
	// Sample mode requires it.
	ScopeSample Scope = "sample"
	// ScopeDatabase is the scope value "database".
	ScopeDatabase Scope = "database"
	// ScopeTable is the scope value "table".
	ScopeTable Scope = "table"
	// ScopeRow is the scope value "row".
	ScopeRow Scope = "row"
	// ScopeColumn is the scope value "column".
	ScopeColumn Scope = "column"
	// ScopeOperation is the scope value "operation".
	ScopeOperation Scope = "operation"
	// ScopePrincipal is the scope value "principal".
	ScopePrincipal Scope = "principal"
	// ScopeConfiguration is the scope value "configuration".
	ScopeConfiguration Scope = "configuration"
)

type Source 

type Source struct {
	OwnerID    string `json:"ownerId"`
	Provider   string `json:"provider"`
	DatabaseID string `json:"databaseId"`
	Kind       string `json:"kind"`
	Reference  string `json:"reference,omitempty"`
}

Source identifies the owner of a layer. OwnerID, Provider, DatabaseID, and Kind are required. Kind is datatug, openvaultdb, ingitdb, application, or adapter.

type Unevaluated 

type Unevaluated struct {
	OperationID string `json:"operationId"`
	LayerID     string `json:"layerId,omitempty"`
	Reason      string `json:"reason"`
}

Unevaluated is one entry in Coverage.Unevaluated. Reason is row_evidence_required, evidence_not_authorized, source_unavailable, unsupported, or budget_exceeded.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.