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 ¶
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 ¶
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 ¶
This section is empty.
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 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