feat(policy): canonical YAML policy schema + examples (2.3a)

PROJECT_SPECS.md

@@ -466,6 +466,74 @@ ws://172.16.10.59:3002/api/ws/gateway?key=gai_827eode3nxa&org=dfy&channels=org:c
 
 ## Policy Configuration
 
+### Canonical Policy-As-Code Schema
+
+Policy-as-code files are validated against the canonical JSON Schema at
+`schemas/policy.schema.json`. The existing `policy.tool_access.yaml` fallback
+file remains supported, and the canonical contract extends that legacy shape
+with explicit sections for PII, budgets, and rate limits so YAML round-trip
+import/export can converge on a single format.
+
+Reference files:
+- `schemas/policy.schema.json`
+- `examples/policies/minimal.yaml`
+- `examples/policies/standard.yaml`
+- `examples/policies/enterprise.yaml`
+
+```yaml
+version: v1
+defaults:
+  ingress:
+    action: redact
+  egress:
+    action: redact
+
+pii:
+  detection: auto
+  default_action: redact
+  entity_rules:
+    "PII:api_key":
+      action: deny
+    "PII:us_ssn":
+      action: tokenize
+
+tool_access:
+  verify_identity:
+    direction: ingress
+    action: confirm
+    allow_pii:
+      "PII:email_address": pass_through
+      "PII:us_ssn": tokenize
+
+budget:
+  scope: user
+  monthly_limit_usd: 500
+  warning_threshold_percent: 90
+  block_on_exceeded: true
+  require_context: true
+
+rate_limits:
+  default:
+    requests: 100
+    window_seconds: 60
+    key: user
+
+deny_tools:
+  - python.exec
+  - bash.exec
+  - code.exec
+  - shell.exec
+network_scopes:
+  - net.
+network_tools:
+  - web.
+  - http.
+  - fetch.
+  - request.
+on_error: block
+model: gpt-4
+```
+
 ### Tool Access Policy (`policy.tool_access.yaml`)
 
 ```yaml
@@ -505,6 +573,7 @@ tool_access:
 - **`tokenize`**: Replace PII with stable token (e.g., `pii_8797942a`)
 - **`redact`**: Apply standard redaction (e.g., `<USER_EMAIL>`, `<USER_SSN>`)
 - **`deny`**: Block the request entirely
+- **`confirm`**: Require an approval/confirmation step before tool execution
 
 ### Global Defaults
 

examples/policies/enterprise.yaml

@@ -0,0 +1,86 @@
+version: v1
+description: Organization-wide policy with dual-direction tool controls, org budgets, and stricter outbound rate limits.
+defaults:
+  ingress:
+    action: redact
+  egress:
+    action: tokenize
+pii:
+  detection: presidio
+  default_action: redact
+  entity_rules:
+    "PII:email_address":
+      action: pass_through
+      description: Customer success workflows may route on raw email addresses.
+    "PII:phone_number":
+      action: tokenize
+      description: Tokenize phone numbers before external transmission.
+    "PII:us_ssn":
+      action: tokenize
+      description: SSNs are always tokenized in enterprise exports.
+    "PII:api_key":
+      action: deny
+      description: Secrets are blocked across all tools.
+tool_access:
+  verify_identity:
+    direction: both
+    action: confirm
+    allow_pii:
+      "PII:email_address": pass_through
+      "PII:phone_number": tokenize
+      "PII:us_ssn": tokenize
+  payment_processor:
+    direction: ingress
+    action: confirm
+    allow_pii:
+      "PII:email_address": pass_through
+      "PII:credit_card": tokenize
+  audit_log:
+    direction: egress
+    allow_pii:
+      "PII:email_address": pass_through
+      "PII:us_ssn": tokenize
+  security_incident_export:
+    direction: egress
+    action: confirm
+    allow_pii:
+      "PII:api_key": deny
+      "PII:jwt": deny
+budget:
+  scope: organization
+  monthly_limit_usd: 10000
+  warning_threshold_percent: 85
+  block_on_exceeded: true
+  require_context: true
+rate_limits:
+  default:
+    requests: 250
+    window_seconds: 60
+    key: organization
+  overrides:
+    payment_processor:
+      requests: 60
+      window_seconds: 60
+      key: organization
+      burst: 10
+    security_incident_export:
+      requests: 10
+      window_seconds: 300
+      key: organization
+deny_tools:
+  - python.exec
+  - bash.exec
+  - code.exec
+  - shell.exec
+  - terraform.apply
+network_scopes:
+  - net.
+  - partner.
+network_tools:
+  - web.
+  - http.
+  - fetch.
+  - request.
+  - webhook.
+on_error: best_effort
+model: gpt-4.1

examples/policies/minimal.yaml

@@ -0,0 +1,24 @@
+version: v1
+description: Minimal baseline policy with safe defaults and network redaction.
+defaults:
+  ingress:
+    action: redact
+  egress:
+    action: redact
+pii:
+  detection: auto
+  default_action: redact
+deny_tools:
+  - python.exec
+  - bash.exec
+  - code.exec
+  - shell.exec
+network_scopes:
+  - net.
+network_tools:
+  - web.
+  - http.
+  - fetch.
+  - request.
+on_error: block
+model: gpt-4o-mini

examples/policies/standard.yaml

@@ -0,0 +1,66 @@
+version: v1
+description: Team-level policy with reusable PII rules, per-tool overrides, budget caps, and user rate limits.
+defaults:
+  ingress:
+    action: redact
+  egress:
+    action: redact
+pii:
+  detection: auto
+  default_action: redact
+  entity_rules:
+    "PII:email_address":
+      action: pass_through
+      description: Allow verified communication tools to receive raw email addresses.
+    "PII:us_ssn":
+      action: tokenize
+      description: Tokenize SSNs before they leave the service boundary.
+    "PII:api_key":
+      action: deny
+      description: Never expose secrets to downstream tools.
+tool_access:
+  verify_identity:
+    direction: ingress
+    action: confirm
+    allow_pii:
+      "PII:email_address": pass_through
+      "PII:us_ssn": tokenize
+  send_marketing_email:
+    direction: ingress
+    allow_pii:
+      "PII:email_address": pass_through
+  data_export:
+    direction: egress
+    allow_pii:
+      "PII:email_address": pass_through
+      "PII:us_ssn": tokenize
+budget:
+  scope: user
+  monthly_limit_usd: 500
+  warning_threshold_percent: 90
+  block_on_exceeded: true
+  require_context: true
+rate_limits:
+  default:
+    requests: 100
+    window_seconds: 60
+    key: user
+  overrides:
+    send_marketing_email:
+      requests: 20
+      window_seconds: 60
+      key: user
+deny_tools:
+  - python.exec
+  - bash.exec
+  - code.exec
+  - shell.exec
+network_scopes:
+  - net.
+network_tools:
+  - web.
+  - http.
+  - fetch.
+  - request.
+on_error: block
+model: gpt-4

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "uvicorn[standard]>=0.24.0",
     "pydantic>=2.5.0",
     "pydantic-settings>=2.1.0",
+    "jsonschema>=4.23.0",
     "presidio-analyzer>=2.2.0",
     "presidio-anonymizer>=2.2.0",
     "spacy>=3.7.0",

requirements.txt

@@ -24,6 +24,7 @@ websockets>=12.0
 # Configuration and Utilities
 python-multipart>=0.0.6
 pyyaml>=6.0.0
+jsonschema>=4.23.0
 
 # Monitoring and Metrics
 prometheus-client>=0.19.0