tebako Documentation

Tebako is a generic packaging and loading ecosystem designed to be runtime-agnostic, platform-agnostic, and payload-agnostic. It allows developers to stitch multiple payload images (application code, data, fonts, runtimes, etc.) into a single executable (a "fat" binary) or a small executable that resolves parts on demand (a "lean" binary).

Core capabilities include:

• Stitch: Combining $N$ payload images and a bootstrap into one executable.
• Load: Recursively mounting payloads into a single Virtual File System (VFS) and transferring control to a declared entrypoint.
• Share: Using a machine-wide content cache so runtimes and payloads are downloaded only once.
• Shim: Automatically managing shims for every executable provided by an installed payload.
• Jail: Enforcing declarative host-filesystem policies per run via the VFS layer.
• Trust: Providing opt-in authentication, signatures, and encryption for packages.

tebako uses a hierarchical key model based on OpenPGP (via rnp-rs) to manage access control without a central authority.

Key Types

• DEKs (Data Keys): These encrypt the actual content blocks. They are persisted as OpenPGP session keys using native wrap/unwrap (PKESK packets).
• Session Keys (Grant Envelopes): Sharing access involves wrapping a DEK for a specific recipient (using ephemeral ECDH). A wrapped DEK combined with a manifest digest acts as a capability: possessing it grants access to that specific subtree.

Access Control Patterns

• Hierarchical Derivation: Subtree keys are derived from a root DEK using HKDF with the file path as the info parameter. A key for /a/b grants access to /a/b/** but cannot access /a/c or /a (one-way derivation).
• Selective Disclosure: A single artifact can serve multiple audiences. The manifest maps specific recipients to specific directories or layers, allowing each recipient to open only their assigned slice.
• Crypto-shredding: Access can be revoked prospectively by re-issuing the manifest without the recipient's envelope, or by rotating the DEK for future versions. Destroying a DEK renders the content unrecoverable everywhere.

The tebako ecosystem operates on a strict 'Contract Graph' where every interface between components is governed by a directed edge (owner → consumer) and a declarative YAML contract.

Core Principles:

• Fail-Closed Verification: Consumers must verify contracts before execution. A mismatch results in a named error identifying both parties.
• Single Ownership: Every interface has exactly one owner, one versioned YAML schema, and one verification point.
• Era-based Security: Anything undeclared is considered 'pre-era (era 1)' and is refused by name; it is never assumed or silently served.

**Key Lifecycle Stages (Contracts):

• C1 (Source Tarball → Runtime Factory): Uses tarball-layout.yaml.
• C2 (Runtime Factory → Loader): Produces a release-manifest.yaml.
• C3 (Runtime Exe ↔ Env Image): Governed by layout.yaml.
• C4 (Exe ↔ Static Libs): Governed by c_api.h and filesystem TU.
• C5 (Handoff): Uses argv/env with contract_version (per Spec 17).

        ┌────────────────────────────────────────────────────────────────┐
        │ tamatebako/ruby — SOURCE FACTORY                               │
        │  out: patched src tarball (tebako-mount-root, SHA256SUMS)      │
        └───────────────┬────────────────────────────────────────────────┘
                        │ C1 tarball-layout.yaml
                        ▼
┌──────────────┐  C19   ┌───────────────────────────────────────────────┐
│ vcpkg        │───────▶│ tebako-runtime-ruby — RUNTIME FACTORY         │
│ baseline     │ tags   │  builds: runtime exe + env image              │
└──────────────┘        │  in:  link unit (tebako-rs artifact)           │
                        │  out: runtime release (exe, image, manifest)   │
                        └──────┬───────────────┬───────────────┬────────┘
                               │ C2 release-   │ C3 exe↔image  │ C4 link-time
                               │ manifest.yaml │ (layout.yaml) │ (c_api.h, fs TU)
                               ▼               ▼               ▼
                        ┌──────────────┐  ┌─────────────┐  ┌───────────────┐
                        │ registries / │  │ runtime exe │  │ static libs   │
                        │ release idx  │  │ (driver in) │  │ (driver, tfs) │
                        └──────┬───────┘  └──────┬───────────────┘
                               │ C12             │ C5 handoff (spec 17, 
                               │ registry.yaml   │ argv/env — contract_version)
                               ▼                 │
┌─────────────┐  C13 store    ┌─────────────────▼───────────────────────┐
│ store       │◀──────────────│ LOADER FAMILY                           │
│ (~/.tebako) │               │ bootstrap · shim · cli · tfs-cli       │
└──────┬------┘               └───┬────────┬─────────┬────────┬─────────┘
       │ C13                      │ C6     │ C7      │ C8     │ C9
       ▼                          ▼        ▼         ▼        ▼
  everything local           package   payload    registry  runtime
                           trailer   manifests          release manifest

Tebako uses a shim-based model to manage executable registration and versioning. Instead of calling binaries directly, you call a tebako-shim (the dispatcher) located in ~/.tebako/shims/.

When a command is invoked, the dispatcher performs the following resolution steps:

1. Payload Version Resolution (First match wins):
   • TEBAKO_<TOOL>_VERSION environment variable.
   • The nearest .tebako-tools.yaml file (walking up from the current working directory).
   • User default version (configured via tebako use <tool>@<version>).
   • The default version specified in the registry.
2. Runtime Resolution:
   • The dispatcher looks at the entrypoint's runtime_requirement.
   • It selects the newest compatible cached runtime.
   • If no compatible runtime is cached, it downloads the newest compatible version.
3. Execution:
   • The dispatcher mounts the payload, the selected runtime(s), and any declared dependency mounts.
   • It applies the jail view (if applicable) and executes the entrypoint.

Note: Swapping runtimes does not require changing the payload, as payloads are immutable and runtime selection happens at dispatch time.

# Example of how a tool might be invoked via the shim
# The shim resolves the version and runtime automatically
tebako-tool --version