PolicyGate AI

AI prepares the infrastructure change. Policy validates it. Only a human can approve the exact plan.

Comment

PolicyGate AI

Inspiration

AI agents are becoming increasingly capable of generating infrastructure changes, but production infrastructure should not be changed simply because an AI decided it was safe.

In enterprise and regulated environments, infrastructure changes usually require more than technical correctness. They may need to satisfy security, availability, backup, networking, cost, and approval requirements, while also preserving evidence of exactly what a human reviewed and authorized.

That led to the core idea behind PolicyGate AI:

AI can prepare the change. Policy can validate it. Only a human can authorize the exact infrastructure plan.

The goal was not to build another autonomous provisioning agent. Instead, I wanted to demonstrate a governance pattern where AI is useful without becoming the final authority.

For the hackathon demonstration, I used production PostgreSQL provisioning on AWS as a concrete infrastructure example, but the architecture is designed as a reusable pattern for broader infrastructure automation.

What it does

PolicyGate turns a plain-English infrastructure request into a governed, auditable approval workflow.

A request can look like:

Provision production PostgreSQL on AWS in us-east-1, require high availability and 30-day backups, and keep the monthly budget below $900.

PolicyGate then performs the following workflow:

  1. Claude parses the request into structured infrastructure intent
  2. Deterministic PolicyGate guardrails validate the request
  3. Terraform configuration is generated
  4. A real AWS-backed Terraform plan is produced using GitHub OIDC
  5. The exact saved Terraform plan is hashed using SHA-256
  6. PolicyGate generates a human-readable Change Approval Document
  7. The document includes the Terraform plan summary and exact plan hash
  8. The document is processed using the Foxit MCP integration
  9. PolicyGate sends it through the Foxit eSign API
  10. PolicyGate reaches AWAITING_HUMAN_APPROVAL and stops
  11. A human reviewer manually reviews and signs the document
  12. PolicyGate verifies that Foxit reports the same envelope as EXECUTED
  13. The signer is verified
  14. The signed PDF is downloaded and hashed
  15. The approved Terraform plan hash is verified again
  16. Only after those checks does the final audit become APPROVED

The agent has no capability to sign its own approval document.

Why the Terraform plan hash matters

One of the most important parts of PolicyGate is binding approval to the exact infrastructure plan.

PolicyGate creates a saved Terraform plan and calculates:

SHA-256(tfplan)

That hash is included in the approval evidence before the human signs.

After the approval is completed, PolicyGate verifies that the plan associated with the approval still matches the same hash.

This prevents an important governance failure:

A human approves one infrastructure plan, but automation later executes a different one.

PolicyGate does not regenerate a new Terraform plan after signing and silently substitute it for the approved plan.

For this hackathon demonstration, terraform apply is intentionally not executed. The project demonstrates the authorization boundary and exact-plan verification without creating production infrastructure.

AI reasoning vs. deterministic policy

A key design decision was separating intent extraction from compliance decisions.

Claude is used to understand the user's natural-language request and convert it into structured intent such as:

  • cloud provider
  • region
  • database engine
  • production environment
  • high availability requirement
  • backup retention
  • budget limit
  • human approval requirement

However, Claude does not determine whether the infrastructure request is compliant.

PolicyGate uses deterministic code to enforce controls such as:

  • encryption
  • high availability
  • backup retention
  • private network exposure
  • budget ceilings
  • managed credentials
  • mandatory human approval

This makes the governance decision reproducible and auditable instead of relying on an LLM judgment call.

Unsafe requests can therefore be blocked before Terraform planning or eSign approval.

How I built it

PolicyGate is implemented primarily in Python with a modular architecture separating:

  • natural-language parsing
  • policy validation
  • infrastructure planning
  • Terraform generation
  • plan integrity verification
  • approval-document generation
  • Foxit integration
  • human approval state management
  • audit generation

Claude

The Anthropic Claude API converts plain-English infrastructure requests into typed structured intent.

For the live demonstration, AI fallback is disabled so the workflow fails closed if the real Claude integration is unavailable.

Terraform and AWS

PolicyGate generates Terraform for an AWS RDS PostgreSQL deployment.

GitHub Actions authenticates to AWS using GitHub OIDC, avoiding long-lived AWS access keys.

The live workflow runs:

  • terraform init
  • terraform validate
  • terraform plan -out=tfplan
  • terraform show

It deliberately does not run:

  • terraform apply
  • terraform destroy

The exact binary tfplan is hashed before approval.

Foxit MCP

PolicyGate uses the official Foxit MCP server for a real document-processing operation in the approval workflow.

This demonstrates how an AI-enabled workflow can interact with Foxit's document tools while still preserving a strict approval boundary.

Foxit eSign

The approval document is routed through the real Foxit eSign API.

The workflow sends the document to the designated human reviewer and then enters:

AWAITING_HUMAN_APPROVAL

At this point:

  • the agent cannot sign
  • the agent cannot approve
  • infrastructure provisioning remains blocked

The workflow can only monitor the existing Foxit envelope.

When the human manually signs and Foxit reports the envelope as EXECUTED, PolicyGate performs final verification.

Human authorization boundary

The central principle of PolicyGate is that preparing a change is different from authorizing a change.

Before approval:

  • Policy checks may pass
  • Terraform may be generated
  • a real Terraform plan may exist
  • the approval document may be generated
  • Foxit eSign may receive the document

But the state remains:

AWAITING_HUMAN_APPROVAL

The AI cannot advance that state itself.

Only a real human signature can move the workflow forward.

After signing, PolicyGate verifies:

  • the same Foxit envelope reached EXECUTED
  • the expected signer matches the verified signer
  • the signed PDF is valid
  • the signed document receives its own SHA-256 hash
  • the approved Terraform plan hash still matches

Only then is the final audit marked:

APPROVED

Challenges I faced

Keeping AI useful without making it the authority

The biggest architectural challenge was deciding exactly where AI should stop.

It would have been easy to let the model determine whether the request was compliant or automatically approve a generated change.

Instead, I intentionally separated:

AI interpretation → deterministic validation → human authorization

That separation became the core design principle of the project.

Binding approval to the exact Terraform plan

A normal approval document can describe a change without proving that the infrastructure later executed is exactly what the human reviewed.

To solve that, PolicyGate hashes the saved binary Terraform plan and carries that hash through the approval and audit lifecycle.

Secure cloud authentication

The live Terraform workflow needed real AWS access without introducing long-lived credentials into the repository.

I implemented GitHub Actions authentication through AWS OIDC and restricted the demo to planning operations.

Integrating multiple live systems

The final workflow combines several independently secured systems:

  • Claude
  • GitHub Actions
  • AWS
  • Terraform
  • Foxit MCP
  • Foxit eSign

Each integration has different authentication, lifecycle, failure, and security requirements.

I built and tested the integrations incrementally before combining them into the final workflow.

Preserving the human stop

One subtle challenge was allowing the workflow to wait for an approval without turning the waiting process into automated authorization.

PolicyGate can poll the status of the existing Foxit envelope, but it cannot create a signature or change the approval state itself.

That distinction is important to the project's governance model.

What I learned

This project reinforced that safe AI automation is not only about model accuracy.

For infrastructure automation, the more important questions can be:

  • Who is allowed to make the final decision?
  • Can that decision be reproduced and audited?
  • Can we prove exactly what was approved?
  • Can AI bypass the approval boundary?
  • Can the approved artifact be cryptographically tied to what happens next?

I also learned that LLMs and deterministic systems work well together when their responsibilities are clearly separated.

Claude is effective at interpreting human intent.

Deterministic policy code is better suited for enforcing hard governance rules.

Foxit provides the human authorization and document lifecycle.

Terraform provides a concrete infrastructure execution plan.

Together, these components create a workflow where automation is powerful but authority remains controlled.

Accomplishments I'm proud of

I am especially proud that the final system demonstrates the complete governance chain using real integrations:

  • Real Claude API parsing
  • Deterministic infrastructure policy validation
  • Real AWS authentication through GitHub OIDC
  • Real Terraform planning
  • Exact binary tfplan SHA-256 binding
  • Human-readable approval evidence
  • Real Foxit MCP document processing
  • Real Foxit eSign routing
  • A hard AWAITING_HUMAN_APPROVAL boundary
  • Manual human signing
  • Foxit EXECUTED verification
  • Signer verification
  • Signed-PDF SHA-256
  • Final audit state of APPROVED

The system also deliberately demonstrates what it does not allow:

  • AI signing its own document
  • AI approving its own infrastructure change
  • Terraform apply before approval
  • replacing the approved plan with a newly generated plan

What's next

PostgreSQL provisioning is only the demonstration use case.

The same PolicyGate governance pattern can be extended to other infrastructure automation, including:

  • Kubernetes deployments
  • cloud networking
  • firewall and security-group changes
  • storage provisioning
  • IAM and security controls
  • compute infrastructure
  • multi-cloud resources
  • other Terraform-managed changes

Future work could also include richer enterprise policy catalogs, approval chains involving multiple reviewers, policy-as-code integrations, infrastructure drift verification, and controlled execution of the exact approved Terraform plan.

The broader vision is to provide a reusable governance layer between AI-generated infrastructure changes and production execution.

AI prepares the change. Policy validates it. A human approves it. And only the exact approved infrastructure plan can move forward.

Built With

Share this project:

Updates

Submission history