access

package
v0.64.2 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package access provides adapter-independent capability policies for DALgo.

Access policies are default-deny and distinguish point reads, existence checks, queries, individual mutation kinds, and the reserved truncate operation. Rules inherit through structural DAL paths; the most-specific rule wins within one policy, while multiple policies compose by intersection.

Secured sessions and databases enforce policies before delegating to an adapter. Policies may be attached globally, carried by context.Context, or captured in a bound database handle. YAML and JSON codecs load the same versioned policy model from any io.Reader.

A denial returns a DeniedError matching ErrAccessDenied. The decision includes the operation, resource, policy name and source, winning rule, and explanation for trusted logs, tests, and administrative tooling.

Index

Constants

View Source 
const (
	// DocumentAPIVersion is the first stable portable policy document version.
	DocumentAPIVersion = "dalgo.io/access/v1"
	AccessPolicyKind   = "AccessPolicy"
	AuditPolicyKind    = "AuditPolicy"
)

Variables

View Source 
var (
	// ErrAccessDenied is matched by all authorization denials.
	ErrAccessDenied = errors.New("dalgo access denied")
	// ErrNotSerializable indicates a policy uses a construct that cannot be
	// represented by a portable policy document.
	ErrNotSerializable = errors.New("dalgo access policy is not serializable")
)
View Source 
var AnyID = anyIDValue{}

AnyID matches any record ID, including an incomplete insert key whose ID is not assigned yet.

Functions

func BindDB 

func BindDB(db dal.DB, ctx context.Context) dal.DB

BindDB captures context policies on the returned DB handle. Passing a later operation context cannot remove them, while additional policies still narrow the capability.

func EncodeAccessPolicy 

func EncodeAccessPolicy(writer io.Writer, codec Codec, policy *AccessPolicy) error

EncodeAccessPolicy validates and writes one AccessPolicy through codec.

func EncodeAuditPolicy 

func EncodeAuditPolicy(writer io.Writer, codec Codec, policy *AuditPolicy) error

EncodeAuditPolicy validates and writes one AuditPolicy through codec.

func MarshalAccessPolicyJSON 

func MarshalAccessPolicyJSON(policy *AccessPolicy) ([]byte, error)

func MarshalAccessPolicyYAML 

func MarshalAccessPolicyYAML(policy *AccessPolicy) ([]byte, error)

func MarshalAuditPolicyJSON 

func MarshalAuditPolicyJSON(policy *AuditPolicy) ([]byte, error)

func MarshalAuditPolicyYAML 

func MarshalAuditPolicyYAML(policy *AuditPolicy) ([]byte, error)

func MustSecureDB 

func MustSecureDB(db dal.DB, options ...DBOption) dal.DB

MustSecureDB wraps db and panics when configuration is invalid.

func SecureDB 

func SecureDB(db dal.DB, options ...DBOption) (dal.DB, error)

SecureDB wraps db with adapter-independent access-policy enforcement.

func SecureReadSession 

func SecureReadSession(session dal.ReadSession, policies ...Policy) dal.ReadSession

SecureReadSession wraps a read session with database-bound policies.

func SecureReadwriteSession 

func SecureReadwriteSession(session dal.ReadwriteSession, policies ...Policy) dal.ReadwriteSession

SecureReadwriteSession wraps a combined session with database-bound policies.

func SecureWriteSession 

func SecureWriteSession(session dal.WriteSession, policies ...Policy) dal.WriteSession

SecureWriteSession wraps a write session with database-bound policies.

func WithPolicy 

func WithPolicy(ctx context.Context, policies ...Policy) context.Context

WithPolicy returns a child context carrying additional restrictive policies. Policies inherited from the parent context are preserved.

Types

type AccessPolicy 

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

AccessPolicy is the declarative hierarchical Policy implementation.

func DecodeAccessPolicy 

func DecodeAccessPolicy(reader io.Reader, codec Codec, options ...DecodeOption) (*AccessPolicy, error)

DecodeAccessPolicy decodes and validates one AccessPolicy from any reader.

func MustPolicy 

func MustPolicy(name string, rules ...Rule) *AccessPolicy

MustPolicy constructs a policy and panics when its declaration is invalid.

func NewPolicy 

func NewPolicy(name string, rules ...Rule) (*AccessPolicy, error)

NewPolicy constructs a default-deny access policy.

func UnmarshalAccessPolicyJSON 

func UnmarshalAccessPolicyJSON(data []byte, options ...DecodeOption) (*AccessPolicy, error)

func UnmarshalAccessPolicyYAML 

func UnmarshalAccessPolicyYAML(data []byte, options ...DecodeOption) (*AccessPolicy, error)

func (*AccessPolicy) Authorize 

func (p *AccessPolicy) Authorize(ctx context.Context, request Request) error

func (*AccessPolicy) Decide 

func (p *AccessPolicy) Decide(_ context.Context, request Request) Decision

func (*AccessPolicy) Name 

func (p *AccessPolicy) Name() string

func (*AccessPolicy) Source 

func (p *AccessPolicy) Source() string

Source returns an optional storage-neutral reference supplied while loading a policy document, such as an object key, URL, database key, or file path.

type AuditDecision 

type AuditDecision struct {
	Audit        bool
	Operation    Operations
	Resource     Resource
	Policy       string
	PolicySource string
	Rule         string
	Effect       string
	Explanation  string
}

AuditDecision explains whether an operation should be emitted to an audit pipeline. It never changes authorization.

type AuditPolicy 

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

AuditPolicy classifies operations with the same hierarchy as AccessPolicy. Its default is IgnoreAudit.

func DecodeAuditPolicy 

func DecodeAuditPolicy(reader io.Reader, codec Codec, options ...DecodeOption) (*AuditPolicy, error)

DecodeAuditPolicy decodes and validates one AuditPolicy from any reader.

func MustAuditPolicy 

func MustAuditPolicy(name string, rules ...Rule) *AuditPolicy

func NewAuditPolicy 

func NewAuditPolicy(name string, rules ...Rule) (*AuditPolicy, error)

func UnmarshalAuditPolicyJSON 

func UnmarshalAuditPolicyJSON(data []byte, options ...DecodeOption) (*AuditPolicy, error)

func UnmarshalAuditPolicyYAML 

func UnmarshalAuditPolicyYAML(data []byte, options ...DecodeOption) (*AuditPolicy, error)

func (*AuditPolicy) Classify 

func (p *AuditPolicy) Classify(_ context.Context, request Request) AuditDecision

func (*AuditPolicy) Name 

func (p *AuditPolicy) Name() string

func (*AuditPolicy) Source 

func (p *AuditPolicy) Source() string

Source returns the storage-neutral reference supplied while loading the policy document.

type Codec 

type Codec interface {
	Decode(io.Reader, *Document) error
	Encode(io.Writer, Document) error
}

Codec decouples policy loading from both its syntax and its storage. A caller may implement this interface for HCL or another representation.

type DBOption 

type DBOption func(*secureDBOptions) error

DBOption configures SecureDB.

func RequireContextPolicy 

func RequireContextPolicy() DBOption

RequireContextPolicy makes missing context-bound authority fail closed.

func WithDatabasePolicies 

func WithDatabasePolicies(policies ...Policy) DBOption

WithDatabasePolicies adds policies that apply to every operation through the secured DB and cannot be widened by a context policy.

type Decision 

type Decision struct {
	Allowed      bool
	Operation    Operations
	Resource     Resource
	Policy       string
	PolicySource string
	Rule         string
	Effect       string
	Explanation  string
}

Decision explains an access-policy result.

type DecodeOption 

type DecodeOption func(*decodeOptions)

func WithSource 

func WithSource(reference string) DecodeOption

WithSource records where a policy document came from. It may be a file path, object key, URL, database key, or any application-defined reference.

type DeniedError 

type DeniedError struct {
	Decision Decision
}

DeniedError is returned when a policy rejects an operation.

func (*DeniedError) Error 

func (e *DeniedError) Error() string

func (*DeniedError) Unwrap 

func (e *DeniedError) Unwrap() error

type Document 

type Document struct {
	APIVersion string           `json:"apiVersion" yaml:"apiVersion"`
	Kind       string           `json:"kind" yaml:"kind"`
	Metadata   DocumentMetadata `json:"metadata" yaml:"metadata"`
	Default    string           `json:"default" yaml:"default"`
	Scopes     []DocumentScope  `json:"scopes" yaml:"scopes"`
}

Document is the storage-neutral representation shared by YAML, JSON, and third-party codecs. YAML is the canonical human-authored encoding.

type DocumentMetadata 

type DocumentMetadata struct {
	Name string `json:"name" yaml:"name"`
}

type DocumentRule 

type DocumentRule struct {
	ID         string   `json:"id" yaml:"id"`
	Effect     string   `json:"effect" yaml:"effect"`
	Operations []string `json:"operations" yaml:"operations"`
}

type DocumentScope 

type DocumentScope struct {
	Path            string          `json:"path,omitempty" yaml:"path,omitempty"`
	CollectionGroup string          `json:"collectionGroup,omitempty" yaml:"collectionGroup,omitempty"`
	OpaqueQuery     bool            `json:"opaqueQuery,omitempty" yaml:"opaqueQuery,omitempty"`
	Rules           []DocumentRule  `json:"rules,omitempty" yaml:"rules,omitempty"`
	Scopes          []DocumentScope `json:"scopes,omitempty" yaml:"scopes,omitempty"`
}

DocumentScope selects exactly one resource kind. Path is a structural path fragment; nested scopes append their path to the containing scope.

type JSONCodec 

type JSONCodec struct{}

func (JSONCodec) Decode 

func (JSONCodec) Decode(reader io.Reader, document *Document) error

func (JSONCodec) Encode 

func (JSONCodec) Encode(writer io.Writer, document Document) error

type Operations 

type Operations uint16

Operations is a set of DAL operations. Leaf operation constants contain one bit; the group constants are immutable convenience unions of those leaves. 

const (
	Get Operations = 1 << iota
	Exists
	Query
	Insert
	Set
	Update
	Delete
	// Truncate is reserved for collection-wide deletion. DALgo does not expose
	// a truncate session method yet, but policies can grant and evaluate it now.
	Truncate

	Read      = Get | Exists | Query
	Write     = Insert | Set | Update | Delete | Truncate
	ReadWrite = Read | Write
)

func (Operations) String 

func (o Operations) String() string

type PathPattern 

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

PathPattern is a structural path prefix. Arguments alternate between a collection name and an ID matcher; a terminal collection name is valid.

func NewPath 

func NewPath(parts ...any) (PathPattern, error)

NewPath builds a structural path pattern.

func Path 

func Path(parts ...any) PathPattern

Path builds a structural path pattern and panics on a malformed shape.

func (PathPattern) String 

func (p PathPattern) String() string

type Policy 

type Policy interface {
	Name() string
	Decide(context.Context, Request) Decision
	Authorize(context.Context, Request) error
}

Policy is a named access capability. Every Policy applied to a secured request must allow every target resource.

type Request 

type Request struct {
	Operation Operations
	Resources []Resource
	// Query retains the structured or opaque query for custom policies and
	// future predicate, projection, index, and cost constraints. It is nil for
	// non-query operations; v1 declarative policies authorize query sources.
	Query dal.Query
}

Request describes one DAL operation over one or more resources.

type Resource 

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

Resource is a policy target. Construct resources through RecordResource, CollectionResource, CollectionGroup, or OpaqueQuery.

func CollectionGroup 

func CollectionGroup(name string) Resource

CollectionGroup returns an explicit collection-group query resource.

func CollectionResourceFor 

func CollectionResourceFor(parent *record.Key, collection string) Resource

CollectionResourceFor returns the structural collection path under parent. A nil parent denotes a root collection.

func OpaqueQuery 

func OpaqueQuery(description string) Resource

OpaqueQuery returns an explicit non-structured query resource.

func RecordResourceForKey 

func RecordResourceForKey(key *record.Key) Resource

RecordResource returns the structural path represented by key.

func (Resource) Kind 

func (r Resource) Kind() ResourceKind

func (Resource) String 

func (r Resource) String() string

type ResourceKind 

type ResourceKind string

ResourceKind distinguishes ordinary hierarchical paths from query resources that cannot safely match a path rule. 

const (
	PathResource            ResourceKind = "path"
	CollectionGroupResource ResourceKind = "collection-group"
	OpaqueQueryResource     ResourceKind = "opaque-query"
)

type Rule 

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

Rule is a declarative policy rule. Use Allow, Deny, Audit, IgnoreAudit, Scope, Collection, Under, Root, CollectionGroupScope, or OpaqueQueryScope.

func Allow 

func Allow(operations Operations, name ...string) Rule

Allow permits operations at the containing scope. The optional name appears in explanations; a deterministic name is generated when omitted.

func Audit 

func Audit(operations Operations, name ...string) Rule

Audit selects matching operations for an application's audit pipeline. It does not grant access and does not persist an audit record itself.

func Collection 

func Collection(collection string, rules ...Rule) Rule

Collection adds a terminal collection segment beneath its containing scope.

func CollectionGroupScope 

func CollectionGroupScope(name string, rules ...Rule) Rule

CollectionGroupScope attaches rules to an explicit collection-group query.

func Deny 

func Deny(operations Operations, name ...string) Rule

Deny rejects operations at the containing scope.

func IgnoreAudit 

func IgnoreAudit(operations Operations, name ...string) Rule

IgnoreAudit excludes matching operations from audit selection.

func OpaqueQueryScope 

func OpaqueQueryScope(rules ...Rule) Rule

OpaqueQueryScope attaches rules to all non-structured queries. It is an intentionally explicit and potentially broad capability.

func Root 

func Root(rules ...Rule) Rule

Root attaches rules at the root of all ordinary path resources.

func Scope 

func Scope(collection string, id any, rules ...Rule) Rule

Scope adds a collection-and-ID segment beneath its containing scope.

func Under 

func Under(pattern PathPattern, rules ...Rule) Rule

Under adds an arbitrary structural path prefix beneath its containing scope.

type YAMLCodec 

type YAMLCodec struct{}

func (YAMLCodec) Decode 

func (YAMLCodec) Decode(reader io.Reader, document *Document) error

func (YAMLCodec) Encode 

func (YAMLCodec) Encode(writer io.Writer, document Document) (err error)

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.