Packs

Ein Pack (.gtpack) ist ein signiertes, in sich geschlossenes Archiv, das alles bündelt, was zum Deployen einer Fähigkeit in die Greentic-Plattform benötigt wird: Flows, WASM-Komponenten, Assets und Metadaten. Packs sind die primäre Distributions- und Deployment-Einheit in Greentic.

Warum Packs?

Greentic ist um ein dynamisches Erweiterungsmodell herum konzipiert: Alles, was nicht zum Plattformkern gehört, wird als Pack ausgeliefert. Dadurch kann die Plattform ohne Neukompilierung oder erneutes Deployment der Kern-Runtime erweitert werden.

Portabel

Komplette Features als einzelne .gtpack-Datei ausliefern. Keine Abhängigkeitsauflösung zur Deployment-Zeit - alles ist gebündelt.

Sicher

Jedes Pack wird per Content-Hash (BLAKE3) gehasht und mit Ed25519 signiert. Die Runtime prüft Integrität und Authentizität vor dem Laden.

Versioniert

Semantische Versionierung verfolgt Kompatibilität. Abhängigkeitsbeschränkungen werden im Manifest deklariert und zur Build-Zeit aufgelöst.

Isoliert

WASM-Komponenten in Packs werden in einer sandboxed WASI Preview 2-Umgebung mit expliziten Capability-Freigaben ausgeführt.

Pack-Struktur

Eine .gtpack-Datei ist ein strukturiertes Archiv mit folgendem Layout:

• Ordnermy-feature.gtpack

  • manifest.cbor Pack-Metadaten (Name, Version, Capabilities, Signaturen)
  • Ordnerflows/

    • main.ygtc Primärer Orchestrierungs-Flow
    • helpers.ygtc Wiederverwendbarer Sub-Flow
    • setup.ygtc Provisionierungs-/Setup-Flow
  • Ordnercomponents/

    • processor.wasm WASM-Komponente (wasm32-wasip2)
  • Ordnerassets/

    • Ordnertemplates/

      • welcome.hbs Handlebars-Template
    • Ordnercards/

      • greeting.json Adaptive-Card-Definition
    • Ordneri18n/

      • en.json Lokalisierungs-Strings
      • id.json
  • sbom.json Software Bill of Materials
  • signature.sig Ed25519-Signatur über den Content-Hash

Eintrag	Format	Zweck
manifest.cbor	CBOR	Pack-Identität, Capabilities, Abhängigkeitsgraph, Flow-/Komponenten-/Asset-Index
flows/*.ygtc	YAML	Orchestrierungsgraphen, die die Ausführungslogik definieren
components/*.wasm	WASM (wasm32-wasip2)	Portierbare, isolierte Codemodule
assets/	Beliebig	Templates, Cards, i18n-Bundles, Bilder und andere statische Ressourcen
sbom.json	SPDX/CycloneDX	Software Bill of Materials für Supply-Chain-Audits
signature.sig	Ed25519	Kryptografische Signatur über den BLAKE3-Content-Hash

Pack-Typen

Greentic verwendet ein Capability-basiertes Typsystem zur Klassifizierung von Packs. Die Capability-ID im Manifest bestimmt, wie die Runtime das Pack behandelt.

Provider-Packs

Provider-Packs verbinden externe Dienste (Messaging-Plattformen, Event-Quellen, Secret Stores) mit der Greentic-Runtime. Jedes Provider-Pack enthält typischerweise Ingress-, Egress- und Operator-WASM-Komponenten plus Setup-/Verifizierungs-Flows.

pack.toml — Telegram messaging provider

[pack]
name = "messaging-telegram"
version = "0.4.6"
description = "Telegram messaging provider for Greentic"
authors = ["Greentic <team@greentic.ai>"]

[capabilities]
id = "greentic.cap.messaging.provider.v1"
provides = ["telegram"]

[flows]
setup_default = "flows/setup.ygtc"
verify_webhooks = "flows/verify.ygtc"

[components]
ingress = "components/messaging-ingress-telegram.wasm"
egress = "components/messaging-provider-telegram.wasm"
operator = "components/telegram.wasm"

[secrets]
required = ["telegram_bot_token"]
optional = ["public_base_url"]

Hinweis

Provider-Packs folgen einer Namenskonvention: messaging-{platform} für Messaging-Provider, events-{source} für Event-Provider.

Anwendungs-Packs

Anwendungs-Packs enthalten die Geschäftslogik - den eigentlichen “digital worker”, der Nachrichten verarbeitet, Ereignisse behandelt und Aktionen orchestriert.

pack.toml — Customer service application

[pack]
name = "customer-service"
version = "1.0.0"
description = "AI-powered customer service digital worker"
authors = ["Your Team <team@example.com>"]

[capabilities]
id = "greentic.cap.app.v1"
provides = ["customer-service"]

[dependencies]
greentic-templates = "^0.4"
greentic-llm-openai = "^0.4"

[flows]
on_message = "flows/on_message.ygtc"
on_escalation = "flows/escalation.ygtc"

[components]
classifier = "components/intent-classifier.wasm"

[assets]
cards = "assets/cards/"
templates = "assets/templates/"
i18n = "assets/i18n/"

Komponenten-Packs

Komponenten-Packs stellen wiederverwendbare WASM-Bausteine bereit, von denen andere Packs abhängen können. Sie enthalten keine Flows - nur Komponenten und ihre Konfiguration.

pack.toml — OpenAI LLM component

[pack]
name = "llm-openai"
version = "0.4.6"
description = "OpenAI-compatible LLM component for Greentic"

[capabilities]
id = "greentic.cap.component.v1"
provides = ["llm"]

[components]
llm = "components/llm-openai.wasm"

[config]
default_model = "gpt-4"
max_tokens = 4096

Ein Pack erstellen

1. Verzeichnisstruktur einrichten

   mkdir -p my-pack/{flows,components,assets}

2. Manifest schreiben

   Erstellen Sie eine pack.toml (oder pack.yaml) im Wurzelverzeichnis Ihres Pack-Ordners:

   my-pack/pack.toml

   [pack]
   name = "my-feature"
   version = "1.0.0"
   description = "A feature pack for handling customer inquiries"
   authors = ["Your Name <you@example.com>"]
   
   [capabilities]
   id = "greentic.cap.app.v1"
   provides = ["customer-service"]
   
   [dependencies]
   greentic-templates = "^0.4"
   
   [flows]
   main = "flows/main.ygtc"
   setup = "flows/setup.ygtc"
   
   [components]
   processor = "components/processor.wasm"
   
   [assets]
   templates = "assets/templates/"
   cards = "assets/cards/"

3. Flows hinzufügen

   Schreiben Sie Orchestrierungs-Flows im .ygtc-(YAML-)Format unter flows/. Das vollständige Schema finden Sie im Flows guide.

4. WASM-Komponenten hinzufügen

   Bauen Sie Ihre Komponenten für das Ziel wasm32-wasip2 und legen Sie die .wasm-Dateien in components/ ab:

   cargo build --target wasm32-wasip2 --release
   cp target/wasm32-wasip2/release/processor.wasm my-pack/components/

5. Pack bauen

   # Using the pack builder CLI
   greentic-pack build ./my-pack
   
   # Or with the GTC CLI
   gtc pack build ./my-pack
   
   # Output: my-feature-1.0.0.gtpack

6. Pack signieren

   # Generate a signing key pair (one-time)
   greentic-pack keygen --output my-key.pem
   
   # Sign the pack
   greentic-pack sign my-feature-1.0.0.gtpack --key my-key.pem
   
   # Verify the signature
   greentic-pack verify my-feature-1.0.0.gtpack --pubkey my-key.pub

Packs verwenden

In einem Bundle

Referenzieren Sie Packs in Ihrer Bundle-Konfiguration, um sie zu deployen:

greentic.demo.yaml

providers:
  messaging-telegram:
    pack: "providers/messaging/messaging-telegram.gtpack"
    setup_flow: "setup_default"
    verify_flow: "verify_webhooks"

apps:
  customer-service:
    pack: "apps/customer-service.gtpack"
    default_flow: "on_message"

Installation aus einer OCI-Registry

Packs werden als OCI-Artefakte über Container-Registries verteilt (z. B. GHCR):

# Pull a pack from the registry
gtc pack pull ghcr.io/greentic/messaging-telegram:0.4.6

# Or reference directly in your bundle config
providers:
  messaging-telegram:
    pack: "oci://ghcr.io/greentic/messaging-telegram:0.4.6"

Pack-Validierung

Achtung

Validieren Sie Packs immer vor dem Deployment. Ungültige Flows oder fehlende Komponenten führen zu Laufzeitfehlern.

# Validate pack structure and manifest
greentic-pack validate ./my-pack.gtpack

# Validate all flows within the pack
greentic-flow doctor --pack ./my-pack.gtpack

# Full verification (signature + content integrity + flow validation)
greentic-pack verify --full ./my-pack.gtpack

Pack-Metadaten (CBOR)

Die Datei manifest.cbor ist der maschinenlesbare Pack-Deskriptor, codiert in CBOR für kompakte binäre Serialisierung. Sie enthält den vollständigen Index von Flows, Komponenten und Assets sowie Capability-Deklarationen und Abhängigkeitsbeschränkungen.

Manifest structure (Rust representation)

struct PackManifest {
    name: String,
    version: String,
    description: String,
    authors: Vec<String>,
    capabilities: Capabilities,
    flows: HashMap<String, FlowEntry>,
    components: HashMap<String, ComponentEntry>,
    assets: HashMap<String, AssetEntry>,
    dependencies: HashMap<String, VersionReq>,
    config: HashMap<String, ConfigValue>,
    signatures: Vec<Signature>,
}

Sicherheitsmodell

Greentic-Packs erzwingen ein mehrschichtiges Sicherheitsmodell - Content-Integrität, Authentizität und Capability-Sandboxing.

Content-Hashing

Jede Datei im Pack wird einzeln mit BLAKE3 gehasht. Der gesamte Pack-Hash ist ein Digest im Merkle-Stil:

pack-hash = blake3(
    manifest_hash ||
    flows_hash ||
    components_hash ||
    assets_hash
)

Dadurch wird jede Änderung - selbst an einem einzelnen Byte - beim Laden erkannt.

Signaturprüfung

Packs werden mit Ed25519 signiert. Die Runtime prüft Signaturen automatisch, bevor ein Pack geladen wird:

# Manual verification
greentic-pack verify my-pack.gtpack --pubkey trusted-keys/publisher.pub

Vertrauenswürdige Publisher

Konfigurieren Sie, welche Signaturschlüssel die Runtime akzeptiert:

greentic.toml

[security]
trusted_publishers = [
    "greentic-official.pub",
    "my-org.pub",
]
reject_unsigned = true

Gefahr

reject_unsigned = false in der Produktion zu setzen, wird dringend abgeraten. Nicht signierte Packs umgehen alle Authentizitätsprüfungen.

Best Practices

1. Semantisch versionieren - semver verwenden, damit Verbraucher kompatible Versionsbereiche deklarieren können
2. Ein Pack, ein Zweck - Packs auf ein einzelnes Feature oder einen einzelnen Provider fokussieren
3. Alle Abhängigkeiten deklarieren - Jede Capability auflisten, die Ihr Pack benötigt
4. Eine SBOM einschließen - Ermöglicht nachgelagerte Sicherheitsaudits und Lizenz-Compliance
5. Jedes Release signieren - Niemals unsignierte Packs in Produktion deployen
6. Vor dem Veröffentlichen validieren - greentic-pack verify --full in Ihrer CI-Pipeline ausführen
7. Capability-IDs konsistent verwenden - Der Namenskonvention greentic.cap.{category}.v{N} folgen

Nächste Schritte

• Komponenten - Lernen, wie man WASM-Komponenten für Packs baut
• Packs bauen - CLI-Befehle für die Pack-Verwaltung
• Pack-Format-Referenz - Vollständige .gtpack-Spezifikation
• Flows - Orchestrierungs-Flows für Ihre Packs schreiben