pyrite

Hardware-Bound & Cloud-Gated Binary Execution and Anti-Tamper Envelope Sealing for Crystal.

---

What is Pyrite?

Pyrite ensures that your compiled Crystal binary only executes on your authorized infrastructure. If an adversary extracts, leaks, steals, or modifies the binary, execution halts immediately before any application logic or secrets are exposed.

Core Security Guarantees

1. Hardware & Cloud Execution Binding: The binary is incomplete at rest. Core operational configuration and keys are sealed inside an envelope that can only be decrypted by the physical motherboard's TPM 2.0 chip (systemd-creds) or Google Cloud Run IAM / Cloud KMS.
2. Real-Time Self-Integrity (Anti-Tamper): At boot, Pyrite calculates the SHA-256 digest of /proc/self/exe and compares it against the authorized hash decrypted from the envelope. Any 1-byte alteration halts the process instantly.
3. Anti-Reverse Engineering: Stripped native LLVM machine code (strip -s) contains zero symbol tables, reflection metadata, or plaintext configuration. Decompilation yields only a dead decryption wrapper.
4. Zero Runtime Overhead: The cryptographic gate runs once during startup (~15–25ms) and adds 0.00% overhead to ongoing request handling. Zero external shard dependencies.

---

Quickstart

1. Add to shard.yml

dependencies:
  pyrite:
    github: renich/pyrite
    version: ~> 0.2.0

2. Bootstrap in Application Code

require "pyrite"
require "kemal"

# Define strongly-typed application configuration
struct AppConfig
  include JSON::Serializable

  getter database_url : String
  getter session_secret : String
  getter api_token : String
end

# 1-line verification & bootstrap:
config = Pyrite.bootstrap!(AppConfig)

puts "Pyrite verified binary integrity. Starting application..."

get "/" do
  "Secure service running on authorized hardware."
end

Kemal.run

3. Zero-Trust Fail-Closed Architecture

Pyrite enforces an absolute zero-trust, fail-closed policy:

• Binaries strictly require an authorized hardware TPM 2.0 or Cloud KMS anchor to unseal their configuration envelope.
• If executed outside an authorized environment (e.g. on an attacker's workstation without the TPM or Cloud IAM role), Pyrite aborts immediately with Pyrite::HardwareAuthError and exits with code 1.
• Secrets and business logic are never exposed to memory outside the designated hardware/cloud trust boundary.

---

Build & Sealing CLI (bin/pyrite)

When installed, Pyrite provides a compiled CLI tool to automate LLVM compilation, ELF symbol stripping, SHA-256 digest hashing, and envelope sealing.

# Build & Seal for Google Cloud Run (KMS):
bin/pyrite build \
    --input=src/main.cr \
    --output=bin/app \
    --target=gcp \
    --kms-key="projects/my-p/locations/global/keyRings/my-r/cryptoKeys/app-key" \
    --config=config/production.json

# Build & Seal for Bare-Metal Fedora (TPM 2.0 / systemd-creds):
bin/pyrite build \
    --input=src/main.cr \
    --output=bin/app \
    --target=baremetal \
    --pcr=0,7 \
    --config=config/production.json

# Build & Seal for AWS (ECS / Lambda / KMS):
bin/pyrite build \
    --input=src/main.cr \
    --output=bin/app \
    --target=aws \
    --kms-key="arn:aws:kms:us-east-1:123456789012:key/..." \
    --config=config/production.json

---

Supported Trust Anchors

Environment	Provider	Root of Trust	Protection
Google Cloud Run	Pyrite::Providers::GCPKMS	Google Cloud IAM + Cloud KMS	BinAuthz + Instance Metadata OIDC
Fedora / Bare-Metal	Pyrite::Providers::SystemdCreds	Host TPM 2.0 (PCR 0,7)	systemd-creds + Linux Kernel IMA
Bare-Metal Direct	Pyrite::Providers::TPM2Direct	/dev/tpmrm0 chip	Direct TPM2 PCR unseal (tpm2-tools)
AWS (ECS / Lambda)	Pyrite::Providers::AWSKMS	IMDSv2 + AWS KMS	AWS IAM Task Role Decrypt

---

Documentation

Exhaustive technical documentation, specifications, and architecture decision records are maintained in reStructuredText under docs/: