accesspolicy

package
v0.2.0-beta.7 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2026 License: AGPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package accesspolicy defines the detached, side-effect-free S3 policy envelope used before policy enforcement is enabled. It deliberately has no dependency on storage, cache, HTTP, runtime settings, or legacy routing.

Index

Constants

View Source 
const (
	// CurrentSchemaVersion is the only snapshot schema this preparatory core
	// understands. A caller must not infer an unknown schema as an enforceable
	// policy.
	CurrentSchemaVersion uint16 = 1

	MaxStableIDLength   = 64
	MaxGroupLength      = 64
	MaxModelLength      = 255
	MaxListValues       = 128
	MaxTotalListValues  = 256
	MaxPriceRatioLength = 32
)

Variables

View Source 
var (
	ErrInvalidReference     = errors.New("invalid access policy reference")
	ErrInvalidList          = errors.New("invalid access policy list")
	ErrInvalidPolicyMode    = errors.New("invalid access policy mode")
	ErrUnsupportedSchema    = errors.New("unsupported access policy schema")
	ErrInvalidLegacyOutcome = errors.New("invalid legacy access policy outcome")
)

Stable errors let callers distinguish invalid input from an unsupported schema without risking an error that includes caller-controlled data.

Functions

func EvaluateAssignedPolicy 

func EvaluateAssignedPolicy(policy AssignedPolicy, publicModel, upstreamModel string, channelID int) []string

EvaluateAssignedPolicy evaluates a normalized assignment against the exact public model, resolved upstream model, and selected channel. It never grants access beyond the legacy authorization outcome; an empty result means only that this assignment adds no denial. Disabled assignments deny all access.

Types

type AccessPolicySnapshot 

type AccessPolicySnapshot struct {
	SchemaVersion    uint16     `json:"schema_version"`
	Mode             PolicyMode `json:"mode"`
	RegistryRevision uint64     `json:"registry_revision"`

	AccountTier   Reference  `json:"account_tier"`
	AccessProfile Reference  `json:"access_profile"`
	AllowedGroups StringList `json:"allowed_groups"`
	AllowedModels StringList `json:"allowed_models"`
	AllowedRoutes StringList `json:"allowed_routes"`

	ContentDigest string `json:"content_digest"`
}

AccessPolicySnapshot contains only policy metadata safe for diagnostics and a canonical content digest. RegistryRevision is a fixed numeric field; this package deliberately offers no arbitrary metadata, map, or opaque payload.

func BuildRequestSnapshot 

func BuildRequestSnapshot(source SnapshotSource) (AccessPolicySnapshot, error)

BuildRequestSnapshot resolves tier/profile references against their current registries and produces a normalized, digested snapshot. Effective route and model lists are the intersection of Account Tier and Key Profile policy. Absent lists inherit the other side, while an explicit empty list denies all. Unknown or disabled references are represented as deny-all constraints so a stale stable ID can never widen access even before the reference finding is applied by the caller.

func NormalizeSnapshot 

func NormalizeSnapshot(input AccessPolicySnapshot) (AccessPolicySnapshot, error)

NormalizeSnapshot validates, bounds, copies, and canonically digests a candidate snapshot. The input ContentDigest is never trusted or preserved.

type AssignedPolicy 

type AssignedPolicy struct {
	Enabled        bool     `json:"enabled"`
	PublicModels   []string `json:"public_models"`
	UpstreamModels []string `json:"upstream_models"`
	ChannelIDs     []int    `json:"channel_ids"`
}

AssignedPolicy is an administrator-owned constraint envelope, separate from mutable user and token fields. A nil list inherits existing access; an explicitly empty list denies every value in that dimension.

func NormalizeAssignedPolicy 

func NormalizeAssignedPolicy(input AssignedPolicy) (AssignedPolicy, error)

NormalizeAssignedPolicy applies the same model-name validators as snapshots and returns detached, sorted sets while preserving nil versus empty lists.

type EvaluationInput 

type EvaluationInput struct {
	Snapshot        AccessPolicySnapshot
	Legacy          LegacyOutcome
	AvailableModels StringList
	AvailableRoutes StringList
}

EvaluationInput supplies a candidate policy and the pre-existing result. AvailableModels and AvailableRoutes are optional inventories. Their absent state means dangling references cannot be determined by this invocation.

type Finding 

type Finding struct {
	Code    string         `json:"code"`
	Subject string         `json:"subject,omitempty"`
	State   ReferenceState `json:"state,omitempty"`
}

Finding is a stable, non-secret diagnostic observation. It does not imply a new authorization or pricing result.

func BlockingFindings 

func BlockingFindings(decision PolicyDecision) []Finding

BlockingFindings filters a decision down to the findings that justify a rejection under scoped enforce: the request's resolved legacy group or model falls outside the policy's lists, or a referenced tier/profile is disabled or unknown. Diagnostic-only findings (empty references, dangling inventories, enforcement notices) are intentionally excluded so audit and enforce stay explainable.

type LegacyOutcome 

type LegacyOutcome struct {
	Allow      bool               `json:"allow"`
	UsingGroup string             `json:"using_group,omitempty"`
	UsingModel string             `json:"using_model,omitempty"`
	Price      LegacyPriceOutcome `json:"price"`
}

LegacyOutcome is the complete legacy outcome that this preparatory core preserves. Accepted allow/group/price values are not trimmed, sorted, or otherwise rewritten. UsingModel carries the model the legacy path resolved; it participates in policy comparison but is not a billing input.

type LegacyPriceOutcome 

type LegacyPriceOutcome struct {
	ModelRatio string `json:"model_ratio,omitempty"`
	GroupRatio string `json:"group_ratio,omitempty"`
}

LegacyPriceOutcome is the only accepted price result shape in PRE1. Ratios are canonical non-negative decimal strings. Accepted strings are copied byte-for-byte; callers must reject or adapt other legacy result shapes at their own boundary rather than placing opaque fields in this envelope.

type ListPresence 

type ListPresence string

ListPresence distinguishes a missing field from an explicitly empty list. This distinction is retained in the digest and in all detached outputs. 

const (
	ListPresenceAbsent        ListPresence = "absent"
	ListPresenceExplicitEmpty ListPresence = "explicit_empty"
	ListPresenceValues        ListPresence = "values"
)

type PolicyDecision 

type PolicyDecision struct {
	Snapshot AccessPolicySnapshot `json:"snapshot"`
	Applied  bool                 `json:"applied"`
	Legacy   LegacyOutcome        `json:"legacy"`
	Findings []Finding            `json:"findings"`
}

PolicyDecision is a detached envelope returned by Evaluate. Applied remains false in PRE1, including for an input that requests enforce, because D04 has not authorized the core to change legacy behavior.

func Evaluate 

func Evaluate(input EvaluationInput) (PolicyDecision, error)

Evaluate returns a detached diagnostic envelope. It intentionally retains the legacy allow, selected group, and price outcome for every mode. Off and audit are explicitly non-applied; enforce is also non-applied until the S3 enforcement contract and migration gate are approved.

func EvaluateRequest 

func EvaluateRequest(mode PolicyMode, source SnapshotSource, registryRevision uint64) (PolicyDecision, error)

EvaluateRequest builds the snapshot and evaluates it against the legacy outcome in one call, stamping the configured mode and registry revision onto the snapshot.

type PolicyMode 

type PolicyMode string

PolicyMode is intentionally separated from application state. PRE1 only reports policy differences; it never changes legacy authorization, route, group, or price behavior. 

const (
	PolicyModeOff     PolicyMode = "off"
	PolicyModeAudit   PolicyMode = "audit"
	PolicyModeEnforce PolicyMode = "enforce"
)

type Reference 

type Reference struct {
	State ReferenceState `json:"state"`
	ID    string         `json:"id,omitempty"`
}

Reference is a bounded, non-secret stable identifier and its resolution state. Empty references carry no ID.

type ReferenceState 

type ReferenceState string

ReferenceState records whether a stable policy reference was absent, known, disabled, or not resolvable. Unknown and disabled are diagnostic states, not permission decisions. 

const (
	ReferenceStateEmpty         ReferenceState = "empty"
	ReferenceStateKnownEnabled  ReferenceState = "known_enabled"
	ReferenceStateKnownDisabled ReferenceState = "known_disabled"
	ReferenceStateUnknown       ReferenceState = "unknown"
)

type SnapshotSource 

type SnapshotSource struct {
	// AccountTierID is the user's persisted stable tier identity.
	AccountTierID string
	// AccessProfileID is the token's persisted stable profile identity.
	AccessProfileID string
	// LegacyTokenGroup is the token's legacy group, used only as the
	// compatibility fallback when AccessProfileID is empty.
	LegacyTokenGroup string
	// UsingGroup is the legacy group the request resolved to.
	UsingGroup string
	// UsingModel is the model the legacy path resolved for this request.
	UsingModel string
	// LegacyAllowed reports the legacy authorization outcome.
	LegacyAllowed bool
	// ModelRatio and GroupRatio are the canonical ratio strings the legacy
	// billing path produced for this request, when known.
	ModelRatio string
	GroupRatio string
}

SnapshotSource carries the request-scoped identities the policy snapshot needs. All fields come from state the caller already loaded for the legacy path, so building a snapshot adds no I/O.

type StringList 

type StringList struct {
	Presence ListPresence `json:"presence"`
	Values   []string     `json:"values,omitempty"`
}

StringList is a canonical detached set. Values are sorted and de-duplicated whenever Presence is ListPresenceValues.

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.