Policy vs Config Files: Clear Boundaries and Purpose Definition

[attackordie]

[RFC] Policy vs Config Files: Clear Boundaries and Purpose Definition

Problem Statement

There's significant confusion in the WebAssembly ecosystem about the distinction between policy files (runtime configuration) and config files (compile-time metadata). This confusion affects:

• Developer understanding of when to use each file type
• Tool interoperability across the WASM ecosystem
• Clear separation of concerns between build-time and runtime
• Supply chain security and verification approaches
• Wassette's role in the broader CNCF WebAssembly specification

Current Confusion Points

What developers are asking:

• "When do I use a policy file vs a config file?"
• "Can I put runtime settings in the CNCF config?"
• "Why do I need two separate files?"
• "What happens if they conflict?"
• "Who controls what information?"

Root cause: Both files contain "configuration" but serve fundamentally different purposes in the WebAssembly lifecycle, yet this distinction isn't clearly documented.

Why Both Files Are Fundamentally Needed

WebAssembly Component Distribution Models

Pre-compiled Components:

Developer → Compile to WASM → Package with Config → Distribute → Runtime
         (build-time)       (config immutable)   (OCI registry)  (policy applied)

Source Code Sharing:

Developer → Share WIT/Source → Recipient Compiles → Runtime
         (WIT definitions)    (config editable)    (policy applied)

The Capability vs Permission Gap

Component declares: "I can access filesystem via wasi:filesystem/types@0.2.0"
  ↓ (Config file captures this capability)
Runtime needs: "In production, only allow /app/data/* access"
  ↓ (Policy file provides this constraint)

Supply Chain Security Benefits

Binary Verification Challenge:

• WebAssembly binaries are complex to analyze and verify
• Hidden capabilities may not be apparent until runtime
• Requires deep technical expertise to audit

Policy Verification Advantage:

# policy.yaml - Human readable and verifiable
filesystem:
  allow_read: ["/app/data/*"]     # ✅ Easy to audit
  deny_write: ["/etc/*"]          # ✅ Clear security intent
network:
  deny: ["*"]                     # ✅ Obvious restriction

Defense-in-Depth Protection: Even if a malicious component passes verification, restrictive policies provide a final security gate that can block unexpected behavior.

Clear Boundary Definition

Config File (application/vnd.wasm.config.v0+json)

Purpose: Component Identity & Capabilities
Owner: Component Publisher (developer/CI system)
Lifecycle: Generated at compile-time, read at runtime for capability validation
Mutability: Editable during compilation, immutable after distribution

What belongs in config:

{
  "created": "2024-09-25T12:00:00Z",
  "architecture": "wasm",
  "os": "wasip2",
  "layerDigests": ["sha256:component_hash"],
  "component": {
    "exports": ["wasi:http/incoming-handler@0.2.0"],
    "imports": ["wasi:filesystem/types@0.2.0"],
    "target": "wasi:http/proxy@0.2.0"
  }
}

Does NOT belong: Runtime limits, security controls, environment settings, deployment policies

Policy File (application/vnd.wasm.policy.v1+yaml)

Purpose: Runtime Security & Resource Control
Owner: Platform Operator (DevOps/security team)
Lifecycle: Created at deploy-time, enforced at runtime
Mutability: Environment-specific, can change without rebuilding component

What belongs in policy:

resources:
  memory_max: "256MB"
  cpu_timeout: "30s"
filesystem:
  allow_read: ["/app/data/*"]
  deny_write: ["/etc/*", "/usr/*"]
network:
  deny: ["*"]
execution:
  sandbox_level: "strict"

Does NOT belong: Component interfaces, build metadata, WASI specifications

Core Principle: Policy Can Only Restrict, Never Expand

Critical Rule: Policy files can only ADD restrictions beyond what the config file permits. They cannot grant capabilities that the component wasn't built with.

# [VALID] Restricts within config capabilities
network:
  outbound:
    allow: ["https://api.payment.com"]    # Subset of HTTP capability
[INVALID] Cannot grant what config doesn't allow
network:

outbound:

allow: ["wss://websocket.example.com"] # WebSocket not in config imports

Key Differences Summary

Aspect	Config File	Policy File
Purpose	Component capabilities	Runtime constraints
Owner	Component publisher	Platform operator
When created	Build time	Deploy time
When applied	Component compilation + runtime validation	Runtime enforcement
Mutability	Immutable after distribution	Mutable per environment
Security role	Declares "what can happen"	Enforces "what will happen"

Real-World Example

Config (component capabilities):

{
  "component": {
    "exports": ["wasi:http/incoming-handler@0.2.0"],
    "imports": ["wasi:http/outgoing-handler@0.2.0", "wasi:filesystem/types@0.2.0"]
  }
}

Production Policy (deployment restrictions):

network:
  outbound:
    allow: ["https://api.payment.com"]  # Subset of HTTP capability
filesystem:
  allow_read: ["/app/static/*"]         # Subset of filesystem capability
  deny_write: ["*"]                     # Block all writes

Development Policy (still bounded by config):

network:
  outbound:
    allow: ["https://api.payment.com"]  # Same as config allows
filesystem:
  allow_write: ["/tmp/debug/*"]         # Subset of filesystem capability

---

The Goal: Make it crystal clear when developers should use config vs policy files, eliminating confusion and enabling secure, flexible WebAssembly deployment with robust supply chain protection.