> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/understand-telys/signed-runtime-trust.md).

# Signed runtime & trust

How Telys verifies a signed release manifest, hashes every runtime artifact, and checks an offline license before activating the native engine — fail-closed, native-only.

The `telys` SDK is pure Python, but the engine it drives — the native runtime and the embedding kernel — ships as a **signed bundle**. Before that bundle is activated, the SDK verifies three things: a release manifest signed by Telys's release key, every on-disk artifact matching the hash the manifest promises, and a valid offline license for this machine. Any check fails and the runtime does not load. This page describes that chain and the API you run yourself.

## What ships signed

A verified install lands under `$TELYS_HOME/runtime/<platform>/` (for example `runtime/macos-arm64/`) and contains the runtime, the kernel, the signed manifest, and the license:

| File                        | Role                                                       |
| --------------------------- | ---------------------------------------------------------- |
| `libty_runtime.<ext>`       | the native runtime (`.dylib` / `.so` / `.dll`)             |
| `libame_kernel.<ext>`       | the embedding kernel                                       |
| `telys_manifest.json`       | the release manifest (versions + expected artifact hashes) |
| `telys_manifest.sig`        | RS256 / PKCS#1 v1.5 signature over the manifest            |
| `license.jwt`               | the offline license token                                  |
| `installed.json`, `pysite/` | install metadata and the runtime's Python site directory   |

## The verification chain

The SDK walks three anchors in order, and every one must pass.

{% stepper %}
{% step %}

#### Verify the release manifest signature

`verify_manifest(manifest_bytes, signature, pubkey=None)` checks `telys_manifest.sig` against `telys_manifest.json` with RS256 / PKCS#1 v1.5 and SHA-256, defaulting to the embedded release public key, and returns the trusted manifest as a dict. A tampered or unsigned manifest fails here, so nothing downstream is believed.
{% endstep %}

{% step %}

#### Verify every artifact hash

For each artifact the manifest describes, `verify_artifact(path, expected_sha256)` recomputes the file's SHA-256 (via `sha256_file`) and compares it in **constant time** to the value the signed manifest promised. A swapped or corrupted `libty_runtime` / `libame_kernel` is rejected here.
{% endstep %}

{% step %}

#### Verify the offline license

`verify_license(token, pubkey=None, *, now, issuer=None, audience=None, product="telys")` validates `license.jwt` strictly and entirely offline against the embedded license public key: it pins the algorithm to RS256, rejects any `crit` header, checks `iss` / `aud` / `ver == 2` and `exp` plus a grace window, and reads the `products.telys` tier and features. Only then is the runtime activated.
{% endstep %}
{% endstepper %}

## Fail-closed and native-only

A verified install is **native-only**. `load_runtime()` loads the signed native runtime for a native or verified install and never silently downgrades a verified install to the local runtime. If the runtime cannot be imported it raises `RuntimeNotInstalled` rather than degrading — the trust model is fail-closed, so an install that does not verify simply does not run.

Importing the package wires it in: `import telys` prepends the verified install's `pysite/` to `sys.path` (a silent no-op when there is none). `TELYS_RUNTIME` can force `"native"` or `"local"` to override auto-detection.

## The embedded trust anchors

The public keys the SDK trusts are shipped **inside the wheel**, so verification needs no network and no external key server:

* `release_public_key()` → `telys/_keys/telys_release_pub.pem` (verifies the manifest)
* `license_public_key()` → `telys/_keys/telys_license_pub.pem` (verifies the license)

Both require the `cryptography` package (a hard SDK dependency). You can override the keys and license expectations via environment — `TELYS_RELEASE_PUBKEY` / `TELYS_RELEASE_PUBKEY_FILE`, `TELYS_LICENSE_PUBKEY` / `TELYS_LICENSE_PUBKEY_FILE`, `TELYS_LICENSE_ISSUER`, and `TELYS_LICENSE_AUDIENCE` — but the defaults are the production trust anchors.

| Constant                    | Default                            |
| --------------------------- | ---------------------------------- |
| `DEFAULT_LICENSE_ISSUER`    | `https://license.algenta.ai`       |
| `DEFAULT_LICENSE_AUDIENCES` | `telys-runtime`, `algenta-runtime` |
| `SUPPORTED_LICENSE_VER`     | `2`                                |
| `PRODUCT`                   | `telys`                            |

## Verify it yourself

The one-command path runs the whole chain and is the recommended check after any install or upgrade:

```bash
telys runtime verify        # exit 0 when signature + hashes + license all pass
```

{% hint style="warning" %}
There is no standalone `telys verify` command — signature verification is `telys runtime verify` plus the `telys.verify` API below.
{% endhint %}

For scripting or auditing, the same primitives are importable. The manifest bytes, signature, expected hashes, and license token all come from the signed bundle in `$TELYS_HOME/runtime/<platform>/`:

```python
import datetime
from telys.verify import (
    release_public_key,
    license_public_key,
    verify_manifest,
    verify_artifact,
    verify_license,
    sha256_file,
)

# The public keys the SDK trusts (from the embedded PEMs).
release_pub = release_public_key()
license_pub = license_public_key()

# 1. Manifest signature -> trusted manifest dict (RS256 / PKCS1v15 / SHA-256).
manifest = verify_manifest(manifest_bytes, signature)

# 2. Artifact integrity -> raises if a file's SHA-256 does not match.
verify_artifact("libty_runtime.dylib", expected_sha256)   # expected value from the manifest

# 3. Offline license -> claims dict; strict, no network, pins RS256, ver == 2.
now = int(datetime.datetime.now(datetime.timezone.utc).timestamp())  # verify_license wants a Unix int
claims = verify_license(license_jwt, now=now)
print(claims["products"]["telys"])   # tier + features
```

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Security overview</strong></td><td>The whole trust posture, end to end.</td><td><a href="https://docs.telys.ai/security/overview.md">Overview</a></td></tr><tr><td><strong>Three trust anchors</strong></td><td>Release key, license key, and artifact hashes in depth.</td><td><a href="https://docs.telys.ai/security/trust-anchors.md">Trust anchors</a></td></tr><tr><td><strong>Verify the runtime signature</strong></td><td>Run the verification chain step by step.</td><td><a href="https://docs.telys.ai/security/runtime-signature-verification.md">Verify the runtime</a></td></tr><tr><td><strong>Verify your install</strong></td><td>Confirm the runtime is installed and trusted.</td><td><a href="https://docs.telys.ai/start-here/verify-install.md">Verify install</a></td></tr></tbody></table>
