secure_policy

README

secure_policy

secure_policy is a high-performance, hybrid Authorization Engine designed for decentralized Go microservices. It implements a two-tier security model combining PBAC (Permission-Based Access Control) for rapid decision-making and ABAC (Attribute-Based Access Control) for context-aware, granular policy enforcement.

It is built to integrate directly with ultimate_db, ensuring that security policies are persisted, transactionally consistent, and easily replicated across a peer-to-peer mesh.

Features

• Hybrid Security Architecture:

• Fast-Path PBAC: O(1) lookups for explicit, static permissions.

• ABAC Fallback: Logic-heavy, attribute-based evaluation for dynamic context (e.g., matching IPs, service names, or time-based conditions).

• Default-Deny Posture: If an error occurs or no policy is found, the engine defaults to false (Deny).

• Deny-Override Logic: Explicit DENY policies always supersede ALLOW policies, ensuring high-security constraints are respected.

• Wildcard Support: Built-in support for subject and action wildcards to simplify administration.

• Transactional Integrity: Leverages ultimate_db ACID transactions to ensure policy updates are atomic.

Usage

1. Initialization

The engine requires a *ultimate_db.DB instance. It maps policies to PolicyPageID (5).

import "github.com/gddisney/secure_policy"

// Initialize with your existing database
policyEngine := secure_policy.NewPolicyEngine(db)

2. PBAC: Granting Permissions

For high-frequency checks, grant explicit permissions that bypass complex attribute logic.

// Allow a specific subject (Ed25519 PubKey) to 'ingest' logs
subject := []byte("...node-pubkey...")
err := policyEngine.GrantPermission(subject, "ingest")

3. ABAC: Evaluating Dynamic Policies

For more complex scenarios, add policies that require specific context (e.g., only allow access from a specific IP).

// Add a policy: Subject X can perform 'read' on 'logs_db' only if IP matches
conditions := map[string]string{"ip": "10.0.0.5"}
policyEngine.AddPolicy(subject, "read", "logs_db", "ALLOW", conditions)

// Evaluate access at runtime
context := map[string]string{"ip": "10.0.0.5"}
if policyEngine.Evaluate(subject, "read", "logs_db", context) {
    // Access granted
}

How It Works

The Authorization Flow

When Evaluate() is called, the engine processes requests in a two-stage pipeline:

1. Fast-Path (PBAC): Checks the perm: key prefix in ultimate_db. If an explicit permission exists, it returns true immediately.
2. Fallback (ABAC): If no explicit permission is found, it queries the policy: key prefix. It searches for specific matches, then falls back to action wildcards (*) and subject wildcards.
3. Conflict Resolution: During evaluation, if any matching policy has an effect of DENY, the engine immediately returns false, overriding any existing ALLOW policies.

Storage Layout

Policies are stored in ultimate_db using the following keys:

• perm:<hex_subject>:<permission>
• policy:<hex_subject>:<action>:<resource>

Integration with Middleware

This engine is designed to be injected into your Router or RPCManager.

// Example Middleware implementation
func AuthMiddleware(pe *secure_policy.PolicyEngine, action string) {
    // ... extract user identity and context ...
    if !pe.Evaluate(userKey, action, "resource_name", runtimeContext) {
        // Reject request
    }
}

License

MIT License.

Documentation

Index

• Constants
• type Policy
• type PolicyEngine
  • func NewPolicyEngine(db *ultimate_db.DB) *PolicyEngine
  • func (pe *PolicyEngine) AddPolicy(subject []byte, action, resource, effect string, conditions map[string]string) error
  • func (pe *PolicyEngine) Evaluate(subject []byte, action, resource string, context map[string]string) bool
  • func (pe *PolicyEngine) GrantPermission(subject []byte, permission string) error
  • func (pe *PolicyEngine) HasPermission(subject []byte, permission string) bool
  • func (pe *PolicyEngine) RemovePolicy(subject []byte, action, resource string) error
  • func (pe *PolicyEngine) RestoreSubject(subject []byte) error
  • func (pe *PolicyEngine) RevokeSubject(subject []byte) error
• type SessionManager
  • func NewSessionManager(db *ultimate_db.DB, key *rsa.PrivateKey) *SessionManager
  • func (sm *SessionManager) IssueCookieToken(subject []byte, ttl time.Duration) (string, string, error)
  • func (sm *SessionManager) RevokeDevice(subject []byte) error
  • func (sm *SessionManager) RevokeSession(jti string, expiry time.Duration) error
  • func (sm *SessionManager) RevokeTokenString(tokenString string) error
  • func (sm *SessionManager) ValidateCookieToken(tokenString string) (string, error)

Constants

const PolicyPageID = ultimate_db.PageID(5)

const SessionPageID = ultimate_db.PageID(6)

SessionPageID is strictly reserved for JTI short-term token blacklists

Types

type Policy

type Policy struct {
	Effect     string            `json:"effect"`     // "ALLOW" or "DENY"
	Conditions map[string]string `json:"conditions"` // Attribute constraints
}

type PolicyEngine

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

func NewPolicyEngine

func NewPolicyEngine(db *ultimate_db.DB) *PolicyEngine

func (*PolicyEngine) AddPolicy

func (pe *PolicyEngine) AddPolicy(subject []byte, action, resource, effect string, conditions map[string]string) error

func (*PolicyEngine) Evaluate

func (pe *PolicyEngine) Evaluate(subject []byte, action, resource string, context map[string]string) bool

Evaluate runs a dual-stage PBAC/ABAC check with strict Deny-Override over unified transactional layers

func (*PolicyEngine) GrantPermission

func (pe *PolicyEngine) GrantPermission(subject []byte, permission string) error

func (*PolicyEngine) HasPermission

func (pe *PolicyEngine) HasPermission(subject []byte, permission string) bool

HasPermission executes an explicit permission lookup path optimized for real-time mesh routing loops

func (*PolicyEngine) RemovePolicy

func (pe *PolicyEngine) RemovePolicy(subject []byte, action, resource string) error

func (*PolicyEngine) RestoreSubject

func (pe *PolicyEngine) RestoreSubject(subject []byte) error

func (*PolicyEngine) RevokeSubject

func (pe *PolicyEngine) RevokeSubject(subject []byte) error

type SessionManager

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

func NewSessionManager

func NewSessionManager(db *ultimate_db.DB, key *rsa.PrivateKey) *SessionManager

func (*SessionManager) IssueCookieToken

func (sm *SessionManager) IssueCookieToken(subject []byte, ttl time.Duration) (string, string, error)

IssueCookieToken generates a JWT bound to the hardware subject

func (*SessionManager) RevokeDevice

func (sm *SessionManager) RevokeDevice(subject []byte) error

RevokeDevice permanently blacklists the hardware identity globally across page structures

func (*SessionManager) RevokeSession

func (sm *SessionManager) RevokeSession(jti string, expiry time.Duration) error

RevokeSession invalidates a specific JWT session token immediately across memory and disk

func (*SessionManager) RevokeTokenString

func (sm *SessionManager) RevokeTokenString(tokenString string) error

RevokeTokenString parses an unverified token to extract the JTI and revokes it.

func (*SessionManager) ValidateCookieToken

func (sm *SessionManager) ValidateCookieToken(tokenString string) (string, error)

ValidateCookieToken checks signature, expiration, and the dual-tier cache/DB blacklists