// SPDX-License-Identifier: CC-BY-SA-4.0
= K9: Self-Validating Components
:toc: preamble
:toclevels: 2
:icons: font
:source-highlighter: rouge

A file format that "eats its own dog food."

== What is K9?

K9 is a Self-Validating Component (SVC) standard built on the **must-just-nickel** triad.
Unlike passive file formats that rely on external applications to interpret them, a `.k9` file
carries its own validation contracts and deployment logic.

== What It Does

* Encodes validation, deployment, and recovery workflows in a single contract file.
* Enforces tiered safety levels (Kennel/Yard/Hunt) before execution.
* Provides signing and verification to support trusted execution.

== Where It Is Going

* Stronger default sandboxing for Hunt components.
* Cleaner CI integration for validation and policy checks.
* Broader templates for common infrastructure and automation tasks.

== Examples

[cols="1,1,2"]
|===
|File |Security Level |Description

|`hello.k9`
|Kennel
|Pure data component. Safe to open anywhere.

|`config.k9.ncl`
|Yard
|Nickel evaluation only. No I/O side effects.

|`deploy.k9.ncl`
|Hunt
|Full triad execution. Requires cryptographic handshake.

|`container-deploy.k9.ncl`
|Hunt
|Multi-service container deployment with rolling deploy, rollback,
cerro-torre image verification, and 3 environments (dev/staging/prod).

|`NOT-a-good-fit.adoc`
|N/A (documentation)
|Honest comparison of k9-svc/a2ml vs alternatives (Helm, Kustomize, Terraform, etc.).
5 DEPRECATE and 10 KEEP verdicts with decision flowchart.
|===

== Container Image

The project Containerfile uses **Chainguard wolfi-base** (not Debian).
Build and run with Podman:

[source,bash]
----
podman build -t k9-svc .
podman run --rm k9-svc
----

See link:GUIDE.adoc[GUIDE.adoc] for the full container deployment walkthrough,
including security level selection guidance.

[IMPORTANT]
====
A `.k9` file is not a document you open; it is a component you unleash.
====

== Quick Start

[source,bash]
----
# Clone the repo
git clone https://github.com/hyperpolymath/standards.git
# Note: K9-SVC is located in standards/k9-svc
cd k9-svc

# Check environment
./must status

# Ensure dependencies (Nickel + Just)
./must ensure

# Install k9-sign (memory-safe Rust signing tool)
cd k9-sign && ./install.sh --user && cd ..

# Generate signing keys
k9-sign keygen primary
k9-sign trust ~/.config/k9/keys/primary.pub

# Register MIME type
./must run register-user

# Validate everything
./must run dogfood

# Security tools
./k9-scan examples/hello.k9        # Static analysis
./must verify examples/hello.k9    # Signature verification
./must --dry-run run examples/hello.k9  # Preview mode
----

== The Triad

[cols="1,2,3"]
|===
|Layer |Component |Function

|**Must**
|Environment Shim
|Detects OS/architecture, ensures Nickel and Just are available

|**Just**
|Orchestration
|Task runner that executes build, validate, deploy recipes

|**Nickel**
|Validation Engine
|Typed configuration language that enforces contracts
|===

== Security Levels (The "Leash")

K9 implements tiered execution to prevent abuse:

[horizontal]
`'Kennel`:: Pure data. No execution. Safe to open anywhere.
`'Yard`:: Nickel evaluation only. No I/O side effects.
`'Hunt`:: Full triad execution. Requires cryptographic handshake.

== Security

K9 takes security seriously. Self-executing components require careful design and implementation.

**⚠️ Important:** K9 is under active security hardening. See our roadmap for production readiness timeline.

**For Users:**

* **Before using K9:** Read link:docs/SECURITY-BEST-PRACTICES.adoc[Security Best Practices]
* **Common questions:** See link:docs/SECURITY-FAQ.adoc[Security FAQ]
* **Report vulnerabilities:** See link:SECURITY.md[Security Policy]

**For Decision Makers:**

* **Executive summary:** link:docs/SECURITY-FOR-DECISION-MAKERS.adoc[Security for Decision Makers]
* **Implementation timeline:** link:docs/SECURITY-ROADMAP.adoc[Security Roadmap]
* **Technical analysis:** link:SECURITY-SOLUTIONS-VS-MITIGATIONS.adoc[Solutions vs Mitigations]

**Current Security Posture:**

- **Kennel/Yard components:** Production-ready (data-only, no execution risks)
- **Hunt components:** Development use only (requires Tier 1-3 hardening)
- **Target:** 95% risk elimination after Tier 1-3 implementation (6-12 months)

**Key Protections:**

* Ed25519 digital signatures for Hunt components (k9-sign)
* Nickel contract validation at runtime
* Three-tier security model (Kennel/Yard/Hunt isolation)
* Root user refusal (--allow-root escape hatch)
* Static analysis (k9-scan with 8 security checks)
* Dry-run preview mode
* Memory-safe Rust signing tool (eliminates injection/corruption)
* Planned: HSM key storage, mandatory sandboxing, formal verification

**Security Tools:**

* `k9-sign` - Memory-safe Ed25519 signing (Rust, 15 tests, 756KB)
* `k9-scan` - Static security analysis (8 checks for malware patterns)
* `must --dry-run` - Preview actions before execution
* `must verify` - Signature verification
* Root refusal by default

== File Recognition

[cols="1,2"]
|===
|Attribute |Value

|Magic Number
|`K9!` (`\x4B\x39\x21`)

|MIME Type
|`application/vnd.k9+nickel`

|Extensions
|`.k9`, `.k9.ncl`
|===

== Repository Structure

[source]
----
k9-svc/
├── must              # Environment shim (POSIX shell)
├── Justfile          # Orchestration recipes
├── pedigree.ncl      # Core schema (The Brain)
├── register.ncl      # MIME registration logic
├── Containerfile     # Chainguard wolfi-base container image
├── README.adoc       # This file
├── SPEC.adoc         # Full specification / whitepaper
├── GUIDE.adoc        # Comprehensive user guide (incl. container deployment)
└── examples/
    ├── hello.k9               # Kennel-level example (pure data)
    ├── config.k9.ncl          # Yard-level example (Nickel evaluation)
    ├── deploy.k9.ncl          # Hunt-level example (full triad)
    ├── container-deploy.k9.ncl  # Hunt-level multi-service container deployment
    └── NOT-a-good-fit.adoc    # Deprecation analysis: k9-svc vs alternatives
----

== Philosophy

The "dogfooding" principle: **a format should be able to validate and deploy itself.**

Traditional formats separate data from logic. This creates:

- **Bit rot**: Data survives, but the tools to interpret it die
- **Platform lock-in**: Files only work with specific applications
- **Silent corruption**: Invalid data isn't detected until runtime failure

K9 solves this by embedding validation contracts (Nickel) and deployment
recipes (Just) directly in the component. If the file can't "eat its own
config," it refuses to run.

== Links

* link:SPEC.adoc[Full Specification]
* link:https://nickel-lang.org[Nickel Language]
* link:https://just.systems[Just Task Runner]

== License

PMPL-1.0-or-later
