> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotvibe.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Model

> How Vibe verifies packages and assigns trust states.

## Trust states

Every `.vibeapp` is assigned one of four trust states when it is opened.

| State                   | Condition                                                                           | UI                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Signed + Trusted**    | Valid Ed25519 signature from a publisher in the user's trust store                  | Green indicator; capabilities shown but not gated                  |
| **Signed + Untrusted**  | Valid signature, publisher not in the user's trust store                            | Yellow warning; prompt to trust publisher or proceed cautiously    |
| **Unsigned (Dev Mode)** | No signature — intended for local development                                       | Orange warning; user explicitly acknowledges running unsigned code |
| **Tampered**            | Signature present but verification fails, or file digests do not match the manifest | Red block; app cannot be opened                                    |

## Verification flow

When a package is opened, the host app runs this sequence:

1. Check for `publisher.signing` in the manifest
2. If absent → classify as **unsigned**
3. If present → verify the detached signature against the public key and the root manifest hash
4. If signature is invalid or any file digest mismatches → classify as **tampered** and block
5. If signature is valid → check whether the publisher's public key is in the user's trust store
6. Classify as **trusted** or **untrusted** accordingly

## Signature algorithm

* **Key type:** Ed25519
* **Hash:** SHA-256 over all package files, sorted by path (BTreeMap order) for determinism
* **Signature format:** Detached signature stored in the archive at `publisher.signing.signatureFile`
* **Public key:** Stored in the archive at `publisher.signing.publicKeyFile`

## Trust store

The user's trust store is maintained by the macOS host app. A publisher is added to the trust store when:

* The user clicks "Trust this publisher" in the untrusted-package prompt
* A package with the publisher's public key is installed via a trusted channel (e.g., the official release)

Removing a publisher from the trust store downgrades future opens of their packages to **Signed + Untrusted** — existing trusted-open sessions are not interrupted.

## Tampered packages

If the host app detects that a package has been modified after signing, it shows a red block with an explanation. The app cannot be opened. There is no bypass. The user must obtain a fresh, unmodified copy from the publisher.