[FEATURE][POLICY]: Policy templates library

## Summary

Implement a comprehensive policy templates library that provides pre-built, compliance-ready policy templates for common use cases, accelerating secure deployments and ensuring best-practice policy configurations.

## Parent Epic

- #2222 Epic: Policy-as-Code Security & Compliance Automation Platform

## Related Issues

- #2223 Unified Policy Decision Point (PDP)
- #2238 Policy GitOps & Version Control
- #1245 Security Clearance Levels Plugin
- #2019 Policy as Code for Tool Access Control

## Problem Statement

Organizations struggle with policy authoring due to:
- **Learning Curve**: Cedar and OPA languages require expertise
- **Best Practices**: Difficult to know optimal policy structures
- **Compliance Mapping**: Unclear how to implement regulatory requirements
- **Repetitive Work**: Same patterns implemented repeatedly across teams
- **Security Gaps**: Homegrown policies often miss edge cases

A curated template library accelerates adoption while ensuring security quality.

## Proposed Solution

### Template Categories

```
templates/
├── compliance/
│   ├── hipaa/
│   │   ├── data-access-controls.cedar
│   │   ├── audit-logging.opa
│   │   └── phi-protection.cedar
│   ├── pci-dss/
│   │   ├── cardholder-data.cedar
│   │   └── network-segmentation.opa
│   ├── sox/
│   │   ├── financial-controls.cedar
│   │   └── separation-of-duties.cedar
│   └── gdpr/
│       ├── data-subject-rights.cedar
│       └── consent-management.opa
├── rbac/
│   ├── basic-roles.cedar
│   ├── hierarchical-roles.cedar
│   └── dynamic-roles.opa
├── abac/
│   ├── attribute-based.cedar
│   ├── time-based-access.opa
│   └── location-based.cedar
├── mcp-specific/
│   ├── tool-access-tiers.cedar
│   ├── server-isolation.opa
│   ├── agent-permissions.cedar
│   └── resource-quotas.opa
└── industry/
    ├── healthcare/
    ├── finance/
    └── government/
```

### Template Schema

```yaml
# Template metadata schema
apiVersion: contextforge.io/v1
kind: PolicyTemplate
metadata:
  name: hipaa-phi-protection
  version: 1.2.0
  description: "HIPAA-compliant PHI access control template"
  category: compliance/hipaa
  compliance_frameworks:
    - HIPAA
    - HITECH
  risk_level: high
  author: ContextForge Security Team
  last_reviewed: 2024-01-15
  
spec:
  engine: cedar  # or opa
  
  # Required parameters
  parameters:
    - name: phi_resource_pattern
      type: string
      description: "Pattern matching PHI resources"
      default: "Resource::\"phi-*\""
      required: true
      
    - name: healthcare_roles
      type: list
      description: "Roles with PHI access"
      default: ["physician", "nurse", "admin"]
      required: true
      
    - name: audit_all_access
      type: boolean
      description: "Enable comprehensive audit logging"
      default: true
      
  # Template content with variable substitution
  template: |
    // HIPAA PHI Protection Policy
    // Generated from template: hipaa-phi-protection v{{version}}
    
    // Permit healthcare providers to access PHI
    permit(
      principal in [{{#each healthcare_roles}}Role::"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}],
      action in [Action::"read_phi", Action::"write_phi"],
      resource matches {{phi_resource_pattern}}
    ) when {
      principal.has_hipaa_training == true &&
      principal.training_expiry > context.current_time
    };
    
    // Forbid access without valid training
    forbid(
      principal,
      action in [Action::"read_phi", Action::"write_phi"],
      resource matches {{phi_resource_pattern}}
    ) when {
      principal.has_hipaa_training != true
    };
    
    {{#if audit_all_access}}
    // All PHI access must be logged
    @audit(level: "detailed", retention: "7years")
    {{/if}}
  
  # Validation rules for instantiated policies
  validation:
    - rule: "healthcare_roles must not be empty"
      check: "len(parameters.healthcare_roles) > 0"
    - rule: "phi_resource_pattern must use Resource type"
      check: "parameters.phi_resource_pattern.startswith('Resource::')"
      
  # Test cases for the template
  tests:
    - name: "Trained physician can read PHI"
      given:
        principal: { role: "physician", has_hipaa_training: true, training_expiry: "2025-01-01" }
        action: "read_phi"
        resource: "phi-patient-123"
        context: { current_time: "2024-06-01" }
      expect: allow
      
    - name: "Untrained user denied PHI access"
      given:
        principal: { role: "physician", has_hipaa_training: false }
        action: "read_phi"
        resource: "phi-patient-123"
      expect: deny
```

### Core Components

#### 1. Template Registry
```python
class PolicyTemplateRegistry:
    """Manage policy template library."""
    
    def __init__(self, template_dirs: list[Path]):
        self.templates: dict[str, PolicyTemplate] = {}
        self._load_templates(template_dirs)
    
    def _load_templates(self, dirs: list[Path]):
        """Load all templates from directories."""
        for dir in dirs:
            for path in dir.rglob("*.yaml"):
                template = self._parse_template(path)
                self.templates[template.metadata.name] = template
    
    def search(
        self,
        category: str = None,
        compliance: str = None,
        engine: str = None,
        query: str = None
    ) -> list[PolicyTemplate]:
        """Search templates with filters."""
        results = list(self.templates.values())
        
        if category:
            results = [t for t in results if t.metadata.category.startswith(category)]
        
        if compliance:
            results = [t for t in results 
                      if compliance in t.metadata.compliance_frameworks]
        
        if engine:
            results = [t for t in results if t.spec.engine == engine]
        
        if query:
            results = [t for t in results 
                      if query.lower() in t.metadata.description.lower()
                      or query.lower() in t.metadata.name.lower()]
        
        return sorted(results, key=lambda t: t.metadata.name)
    
    def get_by_compliance(
        self, 
        framework: str
    ) -> list[PolicyTemplate]:
        """Get all templates for a compliance framework."""
        return [t for t in self.templates.values()
                if framework in t.metadata.compliance_frameworks]
```

#### 2. Template Instantiation Engine
```python
class TemplateInstantiator:
    """Instantiate policy templates with parameters."""
    
    def __init__(self):
        self.renderer = Handlebars()  # Template rendering engine
    
    def instantiate(
        self,
        template: PolicyTemplate,
        parameters: dict,
        validate: bool = True
    ) -> InstantiatedPolicy:
        """Create policy instance from template."""
        # Validate parameters
        if validate:
            self._validate_parameters(template, parameters)
        
        # Merge with defaults
        params = self._merge_defaults(template, parameters)
        
        # Render template
        policy_content = self.renderer.render(
            template.spec.template,
            {**params, "version": template.metadata.version}
        )
        
        # Post-process (format, lint)
        policy_content = self._post_process(
            policy_content, 
            template.spec.engine
        )
        
        return InstantiatedPolicy(
            name=f"{template.metadata.name}-{self._generate_suffix()}",
            source_template=template.metadata.name,
            template_version=template.metadata.version,
            engine=template.spec.engine,
            content=policy_content,
            parameters_used=params,
            created_at=datetime.utcnow()
        )
    
    def _validate_parameters(
        self, 
        template: PolicyTemplate, 
        params: dict
    ):
        """Validate parameters against template spec."""
        for param_spec in template.spec.parameters:
            if param_spec.required and param_spec.name not in params:
                raise MissingParameterError(
                    f"Required parameter '{param_spec.name}' not provided"
                )
            
            if param_spec.name in params:
                value = params[param_spec.name]
                if not self._type_check(value, param_spec.type):
                    raise ParameterTypeError(
                        f"Parameter '{param_spec.name}' must be {param_spec.type}"
                    )
        
        # Run custom validation rules
        for rule in template.spec.validation:
            if not self._evaluate_rule(rule.check, params):
                raise ValidationError(rule.rule)
```

#### 3. Template Testing Framework
```python
class TemplateTestRunner:
    """Run test cases against templates."""
    
    async def run_tests(
        self, 
        template: PolicyTemplate,
        parameters: dict = None
    ) -> TestReport:
        """Run all test cases for a template."""
        # Instantiate with test parameters or defaults
        params = parameters or self._get_test_defaults(template)
        policy = self.instantiator.instantiate(template, params)
        
        results = []
        for test in template.spec.tests:
            result = await self._run_single_test(policy, test)
            results.append(result)
        
        return TestReport(
            template=template.metadata.name,
            total_tests=len(results),
            passed=sum(1 for r in results if r.passed),
            failed=sum(1 for r in results if not r.passed),
            results=results
        )
    
    async def _run_single_test(
        self,
        policy: InstantiatedPolicy,
        test: TemplateTest
    ) -> TestResult:
        """Run a single test case."""
        try:
            decision = await self.pdp.evaluate(
                policy=policy.content,
                principal=test.given.principal,
                action=test.given.action,
                resource=test.given.resource,
                context=test.given.context
            )
            
            passed = (
                (test.expect == "allow" and decision.allowed) or
                (test.expect == "deny" and not decision.allowed)
            )
            
            return TestResult(
                test_name=test.name,
                passed=passed,
                expected=test.expect,
                actual="allow" if decision.allowed else "deny",
                evaluation_trace=decision.trace
            )
        except Exception as e:
            return TestResult(
                test_name=test.name,
                passed=False,
                error=str(e)
            )
```

#### 4. Template Recommendation Engine
```python
class TemplateRecommender:
    """Recommend templates based on requirements."""
    
    async def recommend(
        self,
        requirements: RequirementsSpec
    ) -> list[TemplateRecommendation]:
        """Recommend templates based on requirements."""
        recommendations = []
        
        # Compliance-based recommendations
        for framework in requirements.compliance_frameworks:
            templates = self.registry.get_by_compliance(framework)
            for t in templates:
                recommendations.append(TemplateRecommendation(
                    template=t,
                    reason=f"Required for {framework} compliance",
                    priority="high" if t.metadata.risk_level == "high" else "medium",
                    coverage=self._calculate_coverage(t, requirements)
                ))
        
        # Industry-based recommendations
        if requirements.industry:
            industry_templates = self.registry.search(
                category=f"industry/{requirements.industry}"
            )
            for t in industry_templates:
                recommendations.append(TemplateRecommendation(
                    template=t,
                    reason=f"Recommended for {requirements.industry} industry",
                    priority="medium"
                ))
        
        # Use case matching
        for use_case in requirements.use_cases:
            matching = self._find_matching_templates(use_case)
            recommendations.extend(matching)
        
        # Deduplicate and sort by priority
        return self._dedupe_and_sort(recommendations)
    
    def analyze_gaps(
        self,
        current_policies: list[Policy],
        requirements: RequirementsSpec
    ) -> GapAnalysis:
        """Identify policy gaps and recommend templates."""
        recommendations = await self.recommend(requirements)
        
        gaps = []
        for rec in recommendations:
            if not self._is_covered(rec.template, current_policies):
                gaps.append(PolicyGap(
                    requirement=rec.reason,
                    recommended_template=rec.template,
                    severity=rec.priority
                ))
        
        return GapAnalysis(
            total_requirements=len(recommendations),
            covered=len(recommendations) - len(gaps),
            gaps=gaps,
            compliance_score=self._calculate_compliance_score(
                requirements, gaps
            )
        )
```

### Built-in Templates

#### HIPAA PHI Protection
```cedar
// Template: hipaa-phi-protection
// Protects PHI according to HIPAA requirements

permit(
  principal in [Role::"physician", Role::"nurse", Role::"admin"],
  action in [Action::"read_phi", Action::"write_phi"],
  resource matches Resource::"phi-*"
) when {
  principal.has_hipaa_training == true &&
  principal.background_check == "cleared" &&
  context.access_reason != ""
};
```

#### PCI-DSS Cardholder Data
```rego
# Template: pci-cardholder-data
# Restricts access to cardholder data per PCI-DSS

package pci.cardholder

default allow = false

allow {
  input.principal.role in data.pci_authorized_roles
  input.principal.pci_certified == true
  input.resource.classification == "cardholder_data"
  valid_business_need(input.context.reason)
}

valid_business_need(reason) {
  reason in ["customer_service", "fraud_investigation", "authorized_processing"]
}
```

#### MCP Tool Tiering
```cedar
// Template: mcp-tool-tiers
// Implements tiered access to MCP tools

// Tier 1: Read-only tools
permit(
  principal in Role::"viewer",
  action in [Action::"list_tools", Action::"describe_tool"],
  resource in Server::"*"
);

// Tier 2: Safe execution tools  
permit(
  principal in [Role::"developer", Role::"analyst"],
  action == Action::"invoke_tool",
  resource in Server::"safe-tools-*"
) when {
  resource.risk_level in ["low", "medium"]
};

// Tier 3: All tools (admin only)
permit(
  principal in Role::"admin",
  action == Action::"invoke_tool", 
  resource in Server::"*"
);
```

### Configuration

```yaml
plugins:
  - name: "PolicyTemplateLibrary"
    kind: "policy_templates.plugin.PolicyTemplateLibrary"
    version: "0.1.0"
    hooks: ["api_endpoint", "startup"]
    config:
      template_dirs:
        - "./templates/builtin"
        - "./templates/custom"
        
      defaults:
        validate_on_instantiate: true
        run_tests_before_deploy: true
        
      community:
        enabled: true
        registry_url: "https://templates.contextforge.io"
        auto_update: false
        
      caching:
        enabled: true
        ttl_seconds: 3600
```

### REST API

```
GET  /api/v1/templates                     # List all templates
GET  /api/v1/templates/{name}              # Get template details
POST /api/v1/templates/search              # Search templates
POST /api/v1/templates/{name}/instantiate  # Create policy from template
POST /api/v1/templates/{name}/test         # Run template tests
GET  /api/v1/templates/compliance/{framework}  # Get compliance templates
POST /api/v1/templates/recommend           # Get recommendations
POST /api/v1/templates/analyze-gaps        # Analyze policy gaps
```

## Acceptance Criteria

- [ ] 20+ built-in templates covering major compliance frameworks
- [ ] Template search by category, compliance, engine
- [ ] Parameter validation on instantiation
- [ ] Built-in test cases for each template
- [ ] Template versioning with changelog
- [ ] Recommendation engine based on requirements
- [ ] Gap analysis comparing current policies to templates
- [ ] Community template registry support
- [ ] Both Cedar and OPA template engines

## Implementation Phases

### Phase 1: Core Library
- Template schema definition
- Built-in RBAC templates
- Basic instantiation

### Phase 2: Compliance Templates
- HIPAA, PCI-DSS, SOX, GDPR templates
- Compliance mapping documentation
- Validation rules

### Phase 3: Testing & Recommendation
- Template test runner
- Recommendation engine
- Gap analysis

### Phase 4: Community & Distribution
- Community registry integration
- Template submission workflow
- Auto-update mechanism

## Template Quality Standards

- All templates must have:
  - Comprehensive documentation
  - At least 5 test cases
  - Compliance framework mapping (if applicable)
  - Security review approval
  - Version history

## Security Considerations

- Templates reviewed by security team before inclusion
- Parameter injection prevention
- Template signing for integrity verification
- Audit logging for template instantiation
- Rate limiting on instantiation API

## Dependencies

- #2223 Unified PDP (for policy evaluation)
- #2226 Policy Testing Sandbox (for test execution)
- Handlebars or similar templating engine
- Template registry infrastructure

## References

- [AWS Service Control Policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps_examples.html)
- [Azure Policy Built-in Definitions](https://docs.microsoft.com/en-us/azure/governance/policy/samples/built-in-policies)
- [OPA Policy Library](https://www.openpolicyagent.org/docs/latest/policy-library/)
- [Cedar Policy Examples](https://docs.cedarpolicy.com/policies/syntax-examples.html)

[FEATURE][POLICY]: Policy templates library #2242

Description

Summary

Parent Epic

Related Issues

Problem Statement

Proposed Solution

Template Categories

Template Schema

Core Components

1. Template Registry

2. Template Instantiation Engine

3. Template Testing Framework

4. Template Recommendation Engine

Built-in Templates

HIPAA PHI Protection

PCI-DSS Cardholder Data

MCP Tool Tiering

Configuration

REST API

Acceptance Criteria

Implementation Phases

Phase 1: Core Library

Phase 2: Compliance Templates

Phase 3: Testing & Recommendation

Phase 4: Community & Distribution

Template Quality Standards

Security Considerations

Dependencies

References

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions