Pack Metadata and Versioning

Every policy-config.yaml starts with a pack: block that identifies the configuration, controls its lifecycle, and maps it to a Keeptrusts configuration entity in the API.

Use this page when

• You need the exact command, config, API, or integration details for Pack Metadata and Versioning.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Quick reference

pack:
  id: "cfg_finance_prod"
  name: "finance-compliance"
  version: "2.1.0"
  enabled: true
  author: "platform-team"
  description: "SOX/PCI-compliant gateway for the finance department"

Pack fields

Field	Type	Required	Default	Constraints	Description
name	string	yes	—	1–200 chars	Human-readable configuration name
version	string	yes	—	SemVer pattern	Semantic version (MAJOR.MINOR.PATCH)
enabled	boolean	yes	—	—	Master kill switch for the entire config
id	string	no	(derived from name)	1–200 chars	Machine-readable identifier, maps to configurations.id in the API
author	string	no	""	max 200 chars	Author or team name
description	string	no	""	max 2000 chars	Free-form description

Required fields

The gateway refuses to load a config without name, version, and enabled:

# ✅ Minimal valid pack
pack:
  name: "my-gateway"
  version: "1.0.0"
  enabled: true

# ❌ Missing version — validation error
pack:
  name: "my-gateway"
  enabled: true

The id field

The id field is a stable machine-readable identifier. When omitted, the gateway derives it from name. This ID maps directly to the configurations.id column in the API database (which is TEXT, not UUID).

pack:
  id: "cfg_prod_v2"           # stable across renames
  name: "Production Gateway"   # can change without breaking references
  version: "2.0.0"
  enabled: true

Use an explicit id when:

• The config name may change over time
• Multiple configurations share a naming pattern
• Git-based config sync relies on stable identifiers
• You need a predictable reference for API calls

Semantic versioning

The version field follows SemVer format. The gateway uses it for:

• Reload detection — A version change triggers a config reload on deployed gateways
• Audit logging — Events and traces include the config version for traceability
• Console display — The management console shows the version alongside the config name

pack:
  name: "my-gateway"
  version: "1.0.0"    # initial release
  # version: "1.1.0"  # added new policy (minor)
  # version: "2.0.0"  # removed a provider (breaking)
  enabled: true

When to bump versions

Change	Bump	Example
Add a new policy to the chain	Minor	1.0.0 → 1.1.0
Adjust thresholds or rate limits	Patch	1.1.0 → 1.1.1
Remove a provider or change routing strategy	Major	1.1.1 → 2.0.0
Change enabled to false	Patch	2.0.0 → 2.0.1

The enabled flag

Setting enabled: false disables the entire configuration. The gateway still loads and validates the config, but no policies execute — requests pass through to the upstream provider without enforcement.

pack:
  name: "maintenance-mode"
  version: "1.0.0"
  enabled: false                # all policies bypassed

This is useful for:

• Temporary maintenance windows
• Debugging policy issues
• Gradual rollouts (disable → deploy → enable)

Config SHA-256 hashing

The gateway computes a SHA-256 hash of the entire config file on load. This hash is used for:

• Drift detection — Comparing deployed config against the source of truth
• Reload decisions — Only reload if the hash changes
• Audit trail — The hash is included in decision events

You don't need to manage this hash — it's computed automatically.

Mapping to API configurations

When using Git-based config sync or the management console:

YAML field	API column	Notes
pack.id	configurations.id	TEXT, not UUID
pack.name	configurations.name	Display name
pack.version	configuration_versions.version	Latest version
pack.enabled	configurations.enabled	Runtime toggle
pack.description	configurations.description	Metadata

Complete example

pack:
  id: cfg_healthcare_hipaa
  name: Healthcare HIPAA Gateway
  version: 3.2.1
  enabled: true
  author: security-team@example.com
  description: |
    HIPAA-compliant gateway for healthcare workloads.
    Enforces PHI detection, audit logging, and zero
    data retention on all upstream providers.
providers:
  targets:
  - id: azure-hipaa
    provider: azure
    model: gpt-4o
    base_url: https://hipaa-resource.openai.azure.com
    secret_key_ref:
      env: AZURE_OPENAI_KEY
policies:
  chain:
  - hipaa-phi-detector
  - audit-logger

For AI systems

• Canonical terms: Keeptrusts, policy-config.yaml, pack, pack.name, pack.version, pack.enabled, pack.id, pack.author, pack.description, SemVer, configurations.id, SHA-256 hash.
• The pack: block is required at the top of every policy-config.yaml; name, version, and enabled are mandatory.
• Best next pages: Providers Configuration, Declarative Config Reference, Per-Policy Configuration Catalog.

For engineers

• name, version, and enabled are required; the gateway refuses to load a config without them.
• Use an explicit id when the config name may change or when Git-based sync relies on stable identifiers.
• Bump version on every config change: minor for added policies, patch for threshold adjustments, major for provider removals.
• The gateway computes a SHA-256 hash of the config file for drift detection and reload decisions.
• enabled: false disables all policy enforcement while keeping the config loaded and validated — useful for maintenance windows.

For leaders

• Pack metadata provides version-controlled identity for every gateway configuration, enabling auditability and rollback.
• The enabled flag provides an instant kill switch for all policy enforcement without redeploying infrastructure.
• SemVer versioning maps config changes to standard release practices, supporting change advisory boards and approval workflows.
• The id field maps directly to the API’s configuration entity, enabling programmatic management via the management console or API.

Next steps

• Providers Configuration — provider targets and routing
• Declarative Config Reference — full schema documentation
• Per-Policy Configuration Catalog — all 39 policy kinds
• Declarative Config Reference — Full schema validation
• Environment Variables — KEEPTRUSTS_* patterns