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

# Verify the HYOK release

> Review the HYOK source in the app, check the signed release and rebuild it with the verification kit, and confirm with verify.sh that the stack running in your AWS account matches the release.

Everything that runs in your HYOK stack comes from one signed, reproducible release. You can review the source before you deploy, check the signed release on your own machine, and confirm that the stack in your AWS account runs exactly that release.

The HYOK source code isn't public. It's available only in the Corsa app (**Source audit**) and in the verification kit, and only to workspace Owners and users with the Support role. Everyone with access to the Corsa app is covered by a non-disclosure agreement with Corsa, so you don't need to sign anything extra. Corsa logs every source view and kit download.

***

## Three levels of verification

All three levels start from **Settings** → **Encryption** → **Verify**.

| Level | What you do | What it proves |
| - | - | - |
| [In-app source review](#level-1-review-the-source-in-the-app) | Browse every file of a release in **Source audit** | The code you read is exactly the signed release. Your browser re-hashes each file against the signed manifest |
| [Verification kit](#level-2-check-and-rebuild-the-release-with-the-kit) | Download the kit, check the signature offline, and optionally rebuild the release | The release was built and signed by Corsa's release workflow from the source you have, and a rebuild produces the same files |
| [Running-stack check](#level-3-check-the-running-stack) | Run `verify.sh` in AWS CloudShell | The stack in your account runs the signed release, with signed-code enforcement, key protection, and no outside access in place |

The **Verify** page shows the expected values from the signed manifest next to each command, so you can compare them yourself. Corsa never marks your stack as verified from its own data. The evidence is the output of the commands you run.

***

## What a release contains

| Item | Description |
| - | - |
| `manifest.json` | Release version, source commit, builder image digest, and the SHA-256 of every file |
| `hyok-release.tar.gz` | The release archive: the signed code packages that run in your stack, the Secure Viewer files, and the reviewable source |
| `checksums.txt` | SHA-256 of each signed code package and of the archive |
| `hyok-release.sigstore.json` | A Sigstore signature over the archive, issued to Corsa's release workflow through GitHub OIDC. The public Rekor transparency log records only hashes and the workflow identity, never code |
| **Release digest** | One SHA-256 computed from the manifest. Corsa shows it before you deploy, pins it in your stack, and your stack reports it back |

The code is built inside a builder image pinned by digest. Every code package except the small installer is signed by Corsa's release process, and your stack refuses unsigned code. See [Signed code only](/hyok/setup#signed-code-only).

***

## Level 1: Review the source in the app

<Steps>
  <Step title="Open Source audit">
    In **Settings** → **Encryption** → **Verify**, open **Source audit**. Pick the installed release or any newer one.
  </Step>

  <Step title="Note the release digest">
    Write down the release version and digest. You'll compare them with your stack later.
  </Step>

  <Step title="Review the code">
    Focus on the decryption check (the only code that calls KMS `Decrypt`), the code that reports to Corsa, the installer, and the Secure Viewer files. Each file shows ✓ when your browser's SHA-256 of it matches the signed manifest, or ✗ when it doesn't.
  </Step>
</Steps>

Before an upgrade, open the **diff** view in **Source audit** to see the files added, removed, and changed between your installed release and the new one.

***

## Level 2: Check and rebuild the release with the kit

The verification kit lets you check the release on your own machine and rebuild it.

| Kit file | Description |
| - | - |
| `hyok-release.tar.gz`, `manifest.json`, `checksums.txt`, `hyok-release.sigstore.json` | The signed release |
| `source.tar.gz` | The full HYOK source at the release commit |
| `builder-image.tar` | The builder image (`docker save`). Its digest is in `manifest.json` |
| `build-recipe.json` | The source commit, builder image digest, `SOURCE_DATE_EPOCH`, and build command |
| `verify.sh` | The [running-stack checker](#level-3-check-the-running-stack) |

### Download the kit

On the **Verify** page, pick a release and click **Download verification kit**. Each file comes with its SHA-256. The download links expire after a few hours. The page shows the exact time. Download the kit again to get fresh links.

### Verify the signature

Check the archive's signature with [cosign](https://docs.sigstore.dev/cosign/):

```bash theme={null}
cosign verify-blob \
  --bundle hyok-release.sigstore.json \
  --certificate-identity-regexp '<release identity from the Verify page>' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  hyok-release.tar.gz

sha256sum hyok-release.tar.gz   # must equal the bundle SHA-256 on the Verify page
```

The **Verify** page shows the exact release identity to pass to `--certificate-identity-regexp`.

On macOS, use `shasum -a 256` instead of `sha256sum`.

### Check the files and the release digest

```bash theme={null}
mkdir release && tar -xzf hyok-release.tar.gz -C release && cd release

# Every file matches the manifest and checksums.txt
jq -r '.files[] | "\(.sha256)  \(.path)"' manifest.json | sha256sum -c --quiet
sha256sum -c --quiet checksums.txt

# Recompute the release digest from the manifest
jq -cj '{version, sourceCommit, builderImageDigest, encryptionBrowserVersion, protocolVersion,
         files: [.files[] | {path, sha256, size, language, mediaType, kind}]}' manifest.json \
  | sha256sum
```

The last command must print the release digest shown in the app. Corsa runs the same checks, plus the signature check, before it lets you install or upgrade to a release. It refuses a release that fails any of them, and your stack recomputes the digest again before it installs anything.

### Reproduce the build (optional)

Releases are reproducible. With the same source commit, builder image, and `SOURCE_DATE_EPOCH`, the build produces byte-identical code packages, viewer files, and archive.

<Steps>
  <Step title="Load the builder image">
    ```bash theme={null}
    docker load -i builder-image.tar
    jq . build-recipe.json
    ```

    Check that the loaded image's digest equals `builderImageDigest` in `build-recipe.json` and `manifest.json`.
  </Step>

  <Step title="Unpack the source">
    ```bash theme={null}
    mkdir hyok-source && tar -xzf source.tar.gz -C hyok-source && cd hyok-source
    ```
  </Step>

  <Step title="Run the recorded build">
    Run the `command` from `build-recipe.json` with `SOURCE_DATE_EPOCH` set to the recorded value. You need Docker with Buildx.
  </Step>

  <Step title="Compare the output">
    Compare the rebuilt files with `manifest.json` and `checksums.txt` from the signed release. Never deploy a rebuild: your stack only installs the signed release.
  </Step>
</Steps>

***

## Level 3: Check the running stack

`verify.sh` checks the stack running in your account against the signed release. It's a short, readable bash script that uses only `aws`, `jq`, `curl`, `sha256sum` or `shasum`, `base64`, `xxd`, and `openssl`. It prints a report for your records and **sends nothing to Corsa**.

<Steps>
  <Step title="Open AWS CloudShell">
    Sign in to the AWS account that owns the stack and open CloudShell in the stack's region.
  </Step>

  <Step title="Get verify.sh">
    Upload `verify.sh` and `checksums.txt` from the kit (**Actions** → **Upload file**), or copy the command from the **Verify** page. Read the script before you run it.
  </Step>

  <Step title="Run the check">
    ```bash theme={null}
    bash verify.sh \
      --stack <your-stack-name> \
      --region <your-region> \
      --release-digest <release-digest> \
      --checksums checksums.txt
    ```

    The **Verify** page fills in your stack name, region, and the expected release digest.
  </Step>

  <Step title="Read the report">
    The script prints a PASS or FAIL line for each check and exits with a non-zero status if any check fails. Archive the output with the release materials.
  </Step>
</Steps>

### What verify.sh checks

| Check | Passes when |
| - | - |
| Release | The release your stack reports equals the expected release |
| Code | Each code package running in your stack matches its entry in `checksums.txt` |
| Code signing | Everything except the installer only accepts Corsa-signed code. See [Signed code only](/hyok/setup#signed-code-only) |
| Secure Viewer | The Secure Viewer reports the same release digest |
| Health | The health endpoint returns `ok` with a valid signature, checked with `openssl` against your stack's signing key |
| No outside access | Nothing in the stack trusts, and no key grants access to, anyone outside your account, except AWS services |
| Key protection | The stack's built-in protection for your keys and Cognito users is in place. See [Protected keys](/hyok/setup#protected-keys) |
| Drift | CloudFormation drift detection reports no changes to your keys and Cognito users |

Before an upgrade, `verify.sh` checks the change set instead. See [Upgrades](/hyok/operations#upgrades).

Run the check after setup and after every upgrade or rollback. Expected configuration changes are fine. Any release, code, viewer, code signing, or key protection failure is drift: see [Drift](/hyok/operations#drift).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.