trusted-workload-launcher: default to repo-owned tee-launch.sh

Make INSTALL_CMD and RUN_CMD optional and add a recommended default mode:
when neither is set the launcher runs 'bash tee-launch.sh' from the
pinned commit (under REPO_SUBDIR if set, else repo root). The script's
bytes are covered by source provenance of COMMIT_SHA, so the trust-
bearing config in default mode collapses to REPO_URL + COMMIT_SHA. The
existing RUN_CMD path is preserved as an advanced mode for repos that
cannot host their own entry script; INSTALL_CMD remains optional and
must accompany RUN_CMD.

Aligned changes:

- bin/trusted-workload-launcher: validate INSTALL_CMD requires RUN_CMD,
  drop "INSTALL_CMD must be set" and "RUN_CMD required" gates, add the
  default-mode branch that requires ./tee-launch.sh in target. No exec
  bit required (we invoke 'bash tee-launch.sh'). Refreshed top comment
  and parse_config comment to reflect the new model.
- tests/run-tests.sh: extended fixture repo with c3 (adds
  sub/tee-launch.sh, intentionally non-executable), added
  default_mode_happy, default_mode_missing_script_fails, and
  install_cmd_without_run_cmd_fails.
- README.md, examples/web-app.conf: lead with default mode; advanced
  mode explicitly scoped to "workload repo cannot host its own entry
  script"; clarified that no executable bit is required.
- VERIFY.md: quick path shortened to 4 steps for default mode, with an
  explicit one-line note that advanced mode adds the command audit;
  step 4 covers tee-launch.sh under source provenance and step 5 shows
  the default-mode log lines. Updated the recommended-path Mermaid
  diagram. Smoke transcript annotated that the prior production run
  used advanced mode because Hello-World ships no tee-launch.sh, and
  that the compose-hash binding it demonstrates is identical.
- Root README: Details-table description compressed to a true one-liner
  ("Run a pinned Git commit in a TEE.").

Author: h4x3rotab

README.md

@@ -231,7 +231,7 @@ Implementation details and infrastructure patterns.
 | Example | Description |
 |---------|-------------|
 | [launcher](./launcher) | Generic launcher pattern for Docker Compose apps (auto-update) |
-| [trusted-workload-launcher](./trusted-workload-launcher) | Auditable launcher that pins a workload to a full upstream Git commit SHA (no auto-update). |
+| [trusted-workload-launcher](./trusted-workload-launcher) | Run a pinned Git commit in a TEE. |
 | [prelaunch-script](./prelaunch-script) | Pre-launch script patterns (Phala Cloud) |
 | [private-docker-image-deployment](./private-docker-image-deployment) | Using private Docker registries |
 | [attestation/rtmr3-based](./attestation/rtmr3-based) | RTMR3-based attestation (legacy) |

trusted-workload-launcher/README.md

@@ -1,9 +1,9 @@
 # trusted-workload-launcher
 
-A minimal, auditable launcher image for dstack: given a config file that
+A minimal, auditable launcher image for dstack. Given a config file that
 names an upstream Git repo and a full commit SHA, the launcher fetches that
-exact commit, verifies `HEAD` after checkout, and `exec`s the configured run
-command — with no fallback to branches, tags, or short SHAs.
+exact commit, verifies `HEAD` after checkout, and runs the workload's own
+entry point script — with no fallback to branches, tags, or short SHAs.
 
 "Trusted" in the name refers to what a dstack deployment using this image
 can produce — a *trusted workload deployment* — not to any intrinsic
@@ -13,6 +13,14 @@ auditable image digest and an attested config that names the workload
 commit. Whether the workload at that commit is itself trustworthy is up to
 the auditor.
 
+By convention, **the workload repo provides its own bash entry point at the
+fixed path `tee-launch.sh`** (default mode). This keeps install/build/run
+logic inside the workload repo, where it is covered by source provenance of
+the pinned `COMMIT_SHA` and is **not** a trust-bearing field in the
+launcher config. A verifier therefore only audits two things: the launcher
+image's identity, and the `REPO_URL` + `COMMIT_SHA` pair in the attested
+config.
+
 The launcher image is **generic**: its digest attests the launcher's
 implementation, not the workload. The workload identity comes from the
 config file, which must be attested separately (see [Trust model](#trust-model)).
@@ -56,10 +64,11 @@ launcher image digest ──►  launcher implementation identity
 
 launcher config file  ──►  workload pin
                            (REPO_URL + full COMMIT_SHA U; selects which
-                            upstream commit gets fetched and exec()d)
+                            upstream commit gets fetched and run)
 
                        ──►  workload running inside the TEE
-                           = workload repo at commit U
+                           = workload repo at commit U,
+                             starting from its tee-launch.sh
 ```
 
 The published launcher image is a **generic** runner: the same image digest
@@ -103,17 +112,18 @@ trusted-workload-launcher <config-file>
 ```
 
 The launcher is a single bash script (`bin/trusted-workload-launcher`). It
-depends only on `bash`, `git`, and POSIX coreutils. It is **not** sourced and
-**does not source** the config; the only values executed as shell are
-`INSTALL_CMD` and `RUN_CMD`, which are documented to be intentionally
-executed.
+depends only on `bash`, `git`, and POSIX coreutils. It is **not** sourced
+and **does not source** the config. In default mode, the only bytes it
+executes are those of the workload repo's `tee-launch.sh` at the pinned
+`COMMIT_SHA`. In advanced mode (see below), it additionally executes the
+configured `INSTALL_CMD` / `RUN_CMD` via `bash -c`.
 
 ## Config contract
 
 An env-file with `KEY=VALUE` lines. Comments start with `#`. Surrounding
 matching single or double quotes are stripped (one layer). Unknown keys are
-rejected. The config is parsed, not sourced — no command substitution and no
-shell expansion in the parse step.
+rejected. The config is parsed, not sourced — no command substitution and
+no shell expansion in the parse step.
 
 ### Required
 
@@ -122,32 +132,39 @@ shell expansion in the parse step.
 | `REPO_URL` | Git URL of the upstream workload repo (`https://…` or `git@…`). |
 | `COMMIT_SHA` | **Full** 40-hex SHA-1 or 64-hex SHA-256. Branches, tags, and short SHAs are rejected. |
 | `WORK_DIR` | Local directory used as the checkout. Created if missing. Reused on subsequent runs as long as the existing clone's `origin` URL matches `REPO_URL`. |
-| `INSTALL_CMD` | Shell command run inside the checkout (in `REPO_SUBDIR` if set). Pass `INSTALL_CMD=` to explicitly skip the install step. The key must still be present. |
-| `RUN_CMD` | Shell command `exec`d after the install step. Because `exec` is used, signals reach the child program directly. |
 
 ### Optional
 
 | Key | Meaning |
 | --- | --- |
-| `REPO_SUBDIR` | Relative directory inside the repo to `cd` into before `INSTALL_CMD` and `RUN_CMD`. Must not be absolute and must not contain `..`. |
-| `CHILD_ENV_FILE` | Path to a separate env file. Each `KEY=VALUE` line is `export`ed into the environment seen by `INSTALL_CMD` and `RUN_CMD`. The file is parsed line-by-line just like the main config (not sourced). |
-
-### Multi-line install or run logic
-
-`INSTALL_CMD` and `RUN_CMD` are single-line shell strings — the config is
-line-oriented and the launcher does not implement multi-line value parsing.
-This is intentional: a config that "almost" parses a multi-line script is a
-trust hazard. If you need more than one command, put a script in the
-workload repo at the pinned commit (e.g. `scripts/install.sh`,
-`scripts/run.sh`) and call it:
-
-```
-INSTALL_CMD=./scripts/install.sh
-RUN_CMD=./scripts/run.sh
-```
-
-The script then lives at the same pinned `COMMIT_SHA` as the workload, so
-its bytes are covered by the same audit.
+| `REPO_SUBDIR` | Relative directory inside the repo to `cd` into before running the entry point or `RUN_CMD`. Must not be absolute and must not contain `..`. |
+| `CHILD_ENV_FILE` | Path to a separate env file. Each `KEY=VALUE` line is `export`ed into the environment seen by `tee-launch.sh` / `INSTALL_CMD` / `RUN_CMD`. The file is parsed line-by-line just like the main config (not sourced). |
+| `RUN_CMD` | **Advanced.** Shell command to exec instead of the default `tee-launch.sh`. Use only when the workload repo cannot host its own entry script. |
+| `INSTALL_CMD` | **Advanced.** Shell command to run before `RUN_CMD`. Only valid alongside `RUN_CMD`. |
+
+### Default mode: `tee-launch.sh` in the workload repo
+
+Recommended for every workload you control. The workload repo provides a
+bash script at the fixed path `tee-launch.sh` (at the repo root, or at
+`REPO_SUBDIR/tee-launch.sh` if `REPO_SUBDIR` is set). The launcher runs it
+with `bash tee-launch.sh` after checkout — **no executable bit is
+required**. All install/build/run logic lives in that script; the launcher
+config carries only `REPO_URL` + `COMMIT_SHA` (+ local `WORK_DIR`).
+
+Because the script's bytes are pinned by `COMMIT_SHA` and stored in the
+workload repo, they are covered by source provenance of the pinned commit.
+The verifier does not need to extract or audit any command string out of
+the launcher config.
+
+### Advanced mode: explicit `RUN_CMD` / `INSTALL_CMD`
+
+Use this when the workload repo cannot be modified to add a
+`tee-launch.sh` (e.g. you are pinning a third-party repo unchanged).
+Setting `RUN_CMD` switches the launcher into advanced mode; if you need
+more than one command, set `INSTALL_CMD` to run before `RUN_CMD`. Each is
+a single-line shell string and the launcher does not implement multi-line
+parsing. In this mode both values are trust-bearing config and must be
+audited alongside `COMMIT_SHA`.
 
 ### What the launcher will and will not do
 
@@ -159,21 +176,24 @@ its bytes are covered by the same audit.
   A missing commit is a hard failure.
 * Will not: accept short SHAs. A truncated SHA could resolve ambiguously if
   the upstream history changes.
-* Will not: source the config or `eval` anything beyond `INSTALL_CMD` /
-  `RUN_CMD`, which are executed via `bash -c`.
+* Will not: source the config or `eval` config values. In default mode the
+  launcher executes `bash tee-launch.sh` from the pinned commit; in advanced
+  mode it executes `INSTALL_CMD` / `RUN_CMD` via `bash -c`. Nothing else
+  from the config reaches a shell.
 
 ## Example
 
 See [`examples/web-app.conf`](./examples/web-app.conf). Adapt `REPO_URL`,
-`COMMIT_SHA`, `INSTALL_CMD`, and `RUN_CMD` for your workload.
+`COMMIT_SHA`, and (if you need it) `REPO_SUBDIR` for your workload, and
+make sure the workload repo has a `tee-launch.sh` at the pinned commit.
 
 ```sh
 ./bin/trusted-workload-launcher ./examples/web-app.conf
 ```
 
-The launcher logs the resolved repo, commit, workdir, and commands at
-startup, then logs the verified `HEAD` after checkout, before invoking the
-install and run steps.
+The launcher logs the resolved repo, commit, workdir, and selected mode at
+startup, then logs the verified `HEAD` after checkout, before handing
+control to `tee-launch.sh` (or `INSTALL_CMD` / `RUN_CMD` in advanced mode).
 
 ## Deploying with dstack
 
@@ -227,8 +247,6 @@ configs:
       REPO_URL=https://github.com/example-org/example-web-app.git
       COMMIT_SHA=<full-40-or-64-hex-sha>
       WORK_DIR=/var/lib/trusted-workload-launcher/example-web-app
-      INSTALL_CMD=npm ci --omit=dev
-      RUN_CMD=node server.js
 
 volumes:
   workload-checkout:

trusted-workload-launcher/VERIFY.md

@@ -4,41 +4,47 @@ How a relying party verifies that a dstack CVM is running
 `trusted-workload-launcher` and that the workload commit executed inside the
 TEE is the one they audited.
 
-## Quick path (5 steps)
+## Quick path (default mode, 4 steps)
 
-For a verifier who already trusts dstack's attestation tooling, the whole
-chain comes down to:
+In default mode the workload repo provides its own `tee-launch.sh` at the
+pinned commit, so the trust-bearing config is just `REPO_URL + COMMIT_SHA`
+and the install/run command chain disappears from the verifier's checklist.
+The whole chain is:
 
 ```mermaid
 flowchart LR
-    A[dstack attestation] --> B[image digest<br/>+ compose hash]
-    B --> C[Sigstore attestation<br/>for launcher image]
-    C --> D[GitHub workflow<br/>+ repo + commit]
-    B --> E[config bytes<br/>+ COMMIT_SHA]
-    E --> F[upstream repo<br/>at COMMIT_SHA]
+    A[dstack attestation] --> B[launcher image digest<br/>+ REPO_URL<br/>+ COMMIT_SHA]
+    B --> C[Sigstore attestation<br/>for launcher image digest<br/>= dstack-examples@ref/SHA]
+    B --> D[upstream repo at COMMIT_SHA<br/>incl. tee-launch.sh]
 ```
 
-1. **Pull the dstack attestation** for the CVM with
-   `phala cvms attestation --cvm-id <id> --json`, and verify the TDX quote
-   with the dstack verifier (or trust Phala Cloud's verifier for the lite
-   path).
-2. **Read the attested compose** out of the quote. The launcher image
-   digest and the inline `configs:` block containing `REPO_URL` and
-   `COMMIT_SHA` both live there; both are covered by the dstack
-   `compose-hash` measurement.
-3. **Verify launcher image provenance.** Check the Sigstore attestation on
-   the image digest: it must be signed by the
-   `Dstack-TEE/dstack-examples` GitHub Actions workflow that produced it,
-   from a known repo, ref, and commit.
-4. **Confirm the pinned workload commit** by checking out the upstream
-   repo at `COMMIT_SHA` and reviewing it.
-5. **Spot-check runtime logs** — `phala logs --cvm-id <id>` should show
-   `HEAD verified: <COMMIT_SHA>`. Logs are corroborating only; the trust
-   root is steps 1–4.
-
-If all five line up, the bytes executing in the TEE are exactly the
+1. **Verify the dstack attestation.**
+   `phala cvms attestation --cvm-id <id> --json` and feed the TDX quote
+   into the dstack verifier (or trust the Phala Cloud verifier as a lite
+   path). Read out the deployed launcher image digest and the attested
+   `REPO_URL` + `COMMIT_SHA`.
+2. **Verify launcher image provenance via Sigstore.** Confirm the image
+   digest from step 1 carries a build-provenance attestation signed by
+   the expected `Dstack-TEE/dstack-examples` GitHub Actions workflow at
+   the ref / commit you audited.
+3. **Audit the upstream commit.** Check out the workload repo at
+   `COMMIT_SHA` and review it. In default mode this single review covers
+   the workload code *and* its entry point `tee-launch.sh`; no separate
+   install/run command audit is needed.
+4. **Spot-check runtime logs.** `phala logs --cvm-id <id>` should show
+   `HEAD verified: <COMMIT_SHA>` and `exec in <dir>: bash tee-launch.sh`.
+   Logs are corroborating only; the trust root is steps 1–3.
+
+If all four line up, the bytes executing in the TEE are exactly the
 upstream commit you audited, produced by an audited launcher.
 
+> **Advanced mode adds one step.** If the launcher config sets `RUN_CMD`
+> (and optionally `INSTALL_CMD`) instead of relying on `tee-launch.sh`,
+> those strings are trust-bearing config: read them from the attested
+> compose in step 1 and audit them as if they were source code at the
+> pinned commit. The simplification of the default mode is exactly that
+> this extra step does not exist.
+
 The rest of this document explains how the chain works and what to do at
 each step.
 
@@ -56,16 +62,18 @@ downstream image; the image digest then covers both launcher and pin.
 ```mermaid
 flowchart LR
     L[launcher image<br/>@sha256:&lt;L&gt;] --> CMP
-    P[config bytes<br/>REPO_URL<br/>COMMIT_SHA<br/>RUN_CMD] -.inline configs:.-> CMP
+    P[config bytes<br/>REPO_URL<br/>COMMIT_SHA] -.inline configs:.-> CMP
     CMP[docker-compose.yml] --> CH[compose-hash<br/>= sha256 app_compose]
     CH --> Q[dstack attestation<br/>TDX quote]
 ```
 
 The compose YAML references the generic launcher image by digest and
 provides the launcher's config via a compose `configs:` block (with
-`content:` inline). dstack measures the resulting `app_compose` JSON into
-the quote as the `compose-hash` event, so changing either the image
-reference or the config bytes changes the attestation.
+`content:` inline). In default mode the config is just `REPO_URL` +
+`COMMIT_SHA` + `WORK_DIR`; in advanced mode it also carries `RUN_CMD`
+(and optionally `INSTALL_CMD`). Either way dstack measures the resulting
+`app_compose` JSON into the quote as the `compose-hash` event, so changing
+either the image reference or the config bytes changes the attestation.
 
 This is also the surface that dstack KMS policy governs: a CVM can only
 unwrap KMS-protected secrets while running a compose whose hash matches
@@ -167,42 +175,53 @@ evidence of tampering.
 
 ### 4. Extract and audit the workload pin
 
-Parse the `configs:` content from step 2 and read `REPO_URL`,
-`COMMIT_SHA`, `INSTALL_CMD`, `RUN_CMD` (and optional `REPO_SUBDIR` /
-`CHILD_ENV_FILE`). Then:
+Parse the `configs:` content from step 2 and read `REPO_URL` and
+`COMMIT_SHA` (plus optional `REPO_SUBDIR` / `CHILD_ENV_FILE`). In default
+mode there are no `INSTALL_CMD` / `RUN_CMD` strings to audit — the entry
+point is the fixed-path `tee-launch.sh` in the workload repo, which is
+covered by source provenance of the pinned commit. In advanced mode
+(`RUN_CMD` present) also read `RUN_CMD` and any `INSTALL_CMD` and treat
+them as trust-bearing config.
 
 ```sh
 git -C <workload-checkout> rev-parse --verify <COMMIT_SHA>
 ```
 
 Confirm the upstream repo at `REPO_URL` contains `COMMIT_SHA`, and review
-the workload at that commit. This is the code that actually serves
-traffic.
+the workload at that commit, including `tee-launch.sh` in default mode.
+This is the code that actually serves traffic.
 
 ### 5. Spot-check runtime logs
 
 ```sh
 phala logs --cvm-id <id> -n 200
 ```
 
-Expected:
+Default mode expected:
 
 ```
 [trusted-workload-launcher] checking out <COMMIT_SHA>
 [trusted-workload-launcher] HEAD verified: <COMMIT_SHA>
-[trusted-workload-launcher] exec in <WORK_DIR>[/<REPO_SUBDIR>]: <RUN_CMD>
+[trusted-workload-launcher] mode:     default (workload repo tee-launch.sh)
+[trusted-workload-launcher] exec in <WORK_DIR>[/<REPO_SUBDIR>]: bash tee-launch.sh
 ```
 
-These show the launcher reached the post-checkout state. They are not
-signed, so they don't replace steps 1–4 — they corroborate.
+Advanced mode shows the explicit `RUN_CMD` instead of `bash tee-launch.sh`
+on the last line. Either way these lines show the launcher reached the
+post-checkout state. They are not signed, so they don't replace
+steps 1–4 — they corroborate.
 
 A workload that needs signed runtime evidence should produce its own
 attested output (see [Limitations](#limitations)).
 
 ## Reference: production smoke transcript
 
 A real verification of this example was exercised against production
-Phala on 2026-05-11 using the recommended compose-mounted-config path:
+Phala on 2026-05-11 using the recommended compose-mounted-config path.
+The pinned upstream (`octocat/Hello-World`) does not host a
+`tee-launch.sh`, so the smoke used **advanced mode** to set `RUN_CMD`
+inline; default-mode behavior is covered by the launcher's own test
+suite. The compose-hash binding it demonstrates is identical:
 
 | Field | Value |
 | --- | --- |