Documentation
¶
Overview ¶
Package episodic provides namespace encoding/decoding helpers and OPA policy integration for the namespaced episodic memory system.
Index ¶
- func BuildSQLFilter(filter map[string]interface{}) (string, []interface{})
- func DecodeNamespace(encoded string) ([]string, error)
- func EncodeNamespace(segments []string, maxDepth int) (string, error)
- func MatchesSuffix(encoded string, suffix []string) bool
- func NamespaceDepth(encoded string) int
- func NamespaceHasPrefix(encoded, prefixEncoded string) bool
- func NamespaceMatchesExact(encoded, prefixEncoded string) bool
- func NamespacePrefixPattern(prefixEncoded string) string
- func NamespaceTruncate(encoded string, depth int) string
- func ParseAttributeFilter(raw json.RawMessage) (map[string]interface{}, error)
- type AuthzDecision
- type PolicyBundle
- type PolicyContext
- type PolicyEngine
- func (e *PolicyEngine) Bundle() PolicyBundle
- func (e *PolicyEngine) EvaluateAuthz(ctx context.Context, operation string, namespace []string, key string, ...) (AuthzDecision, error)
- func (e *PolicyEngine) ExtractAttributes(ctx context.Context, namespace []string, key string, ...) (map[string]interface{}, error)
- func (e *PolicyEngine) InjectFilter(ctx context.Context, nsPrefix []string, filter map[string]interface{}, ...) ([]string, map[string]interface{}, error)
- func (e *PolicyEngine) InjectFilterParts(ctx context.Context, nsPrefix []string, filter map[string]interface{}, ...) ([]string, map[string]interface{}, error)
- func (e *PolicyEngine) IsAllowed(ctx context.Context, operation string, namespace []string, key string, ...) (bool, error)
- func (e *PolicyEngine) Reload(ctx context.Context, policyDir string) error
- func (e *PolicyEngine) ReplaceBundle(ctx context.Context, bundle PolicyBundle) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildSQLFilter ¶
BuildSQLFilter builds a parameterized SQL WHERE clause fragment and args for the given attribute filter. Keys match JSONB fields in policy_attributes. Supported forms: bare scalar, {"in": [...]}, {"gt"|"gte"|"lt"|"lte": value}.
func DecodeNamespace ¶
DecodeNamespace decodes a storage string back into a []string namespace.
func EncodeNamespace ¶
EncodeNamespace encodes a []string namespace into a single storage string. Each segment is percent-encoded (url.PathEscape), then joined with \x1e (RS). Returns an error if any segment is empty or if depth > maxDepth.
func MatchesSuffix ¶
MatchesSuffix returns true if the decoded namespace ends with each segment in suffix.
func NamespaceDepth ¶
NamespaceDepth returns the number of segments in the encoded namespace.
func NamespaceHasPrefix ¶
NamespaceHasPrefix returns true if encoded == prefixEncoded OR starts with prefixEncoded + RS.
func NamespaceMatchesExact ¶
NamespaceMatchesExact returns true if encoded equals the encoded prefix exactly.
func NamespacePrefixPattern ¶
NamespacePrefixPattern returns the SQL LIKE pattern that matches namespaces under the given prefix. The pattern matches the prefix exactly or any descendant, using the RS separator as the delimiter so "users\x1ealice" never matches "users\x1ealiced".
func NamespaceTruncate ¶
NamespaceTruncate returns the first depth segments of the encoded namespace, re-encoded. If depth >= actual depth, returns the encoded namespace unchanged.
func ParseAttributeFilter ¶
func ParseAttributeFilter(raw json.RawMessage) (map[string]interface{}, error)
ParseAttributeFilter parses a flat JSON attribute filter map from the request. Returns it as-is; validation happens at query time.
Types ¶
type AuthzDecision ¶
AuthzDecision is the structured authz policy result.
type PolicyBundle ¶
type PolicyBundle struct {
Authz string `json:"authz"`
Attributes string `json:"attributes"`
Filter string `json:"filter"`
}
PolicyBundle contains source text for the three episodic Rego policies.
type PolicyContext ¶
type PolicyContext struct {
UserID string `json:"user_id"`
ClientID string `json:"client_id"`
JWTClaims map[string]interface{} `json:"jwt_claims"`
}
PolicyContext contains the caller's identity for OPA policy evaluation.
type PolicyEngine ¶
type PolicyEngine struct {
// contains filtered or unexported fields
}
PolicyEngine evaluates the three OPA policies for episodic memory:
- Authz policy — controls read/write/delete access per (namespace, key).
- Attribute extraction policy — extracts plaintext policy_attributes from request context.
- Search filter injection policy — narrows namespace_prefix + adds attribute_filter constraints.
func NewPolicyEngine ¶
func NewPolicyEngine(ctx context.Context, policyDir string) (*PolicyEngine, error)
NewPolicyEngine creates a PolicyEngine. If policyDir is non-empty, policies are loaded from that directory; otherwise the built-in defaults are used.
func (*PolicyEngine) Bundle ¶
func (e *PolicyEngine) Bundle() PolicyBundle
Bundle returns the currently active policy sources.
func (*PolicyEngine) EvaluateAuthz ¶
func (e *PolicyEngine) EvaluateAuthz(ctx context.Context, operation string, namespace []string, key string, value map[string]interface{}, index map[string]string, pc PolicyContext) (AuthzDecision, error)
EvaluateAuthz evaluates the authz policy and returns the decision.
func (*PolicyEngine) ExtractAttributes ¶
func (e *PolicyEngine) ExtractAttributes(ctx context.Context, namespace []string, key string, value map[string]interface{}, index map[string]string, pc PolicyContext) (map[string]interface{}, error)
ExtractAttributes evaluates the attribute extraction policy and returns the plaintext policy_attributes to store alongside the memory.
func (*PolicyEngine) InjectFilter ¶
func (e *PolicyEngine) InjectFilter(ctx context.Context, nsPrefix []string, filter map[string]interface{}, pc PolicyContext) ([]string, map[string]interface{}, error)
InjectFilter evaluates the search filter injection policy and returns the effective namespace_prefix and merged attribute_filter to use for search.
func (*PolicyEngine) InjectFilterParts ¶
func (e *PolicyEngine) InjectFilterParts(ctx context.Context, nsPrefix []string, filter map[string]interface{}, pc PolicyContext) ([]string, map[string]interface{}, error)
InjectFilterParts evaluates the search filter injection policy and returns the effective namespace_prefix plus policy-supplied attribute_filter without merging it into the caller filter. Search paths that need to preserve duplicate caller/policy constraints should normalize both filters together.
func (*PolicyEngine) IsAllowed ¶
func (e *PolicyEngine) IsAllowed(ctx context.Context, operation string, namespace []string, key string, pc PolicyContext) (bool, error)
IsAllowed evaluates the authz policy and returns true if the operation is allowed.
func (*PolicyEngine) Reload ¶
func (e *PolicyEngine) Reload(ctx context.Context, policyDir string) error
Reload hot-reloads policies from policyDir. Thread-safe.
func (*PolicyEngine) ReplaceBundle ¶
func (e *PolicyEngine) ReplaceBundle(ctx context.Context, bundle PolicyBundle) error
ReplaceBundle validates and hot-swaps policies from source text.
Source Files