> ## 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.

# Operate HYOK: upgrades, health, and access

> Upgrade or roll back the HYOK stack yourself with CloudFormation change sets, monitor its signed health endpoint, respond to drift, and control or cut off decryption.

## Upgrades

Corsa publishes new HYOK releases for security fixes and features. Upgrading is **optional**:

* There's no support window. Older releases keep working, and Corsa never blocks decryption because your stack runs an older release.
* Each release is labeled **Security** or **Feature**. Corsa emails your workspace Owners and shows an in-app notification when a release ships, and sends reminders for security releases.
* You decide when to upgrade, and you run the upgrade yourself.

Only a workspace **Owner** can upgrade. Users with the Support role can review releases and diffs.

<Note>
  Stack managed with Terraform? Corsa hides **Upgrade stack** and shows **Get Terraform template** instead. See [Install HYOK with Terraform → Upgrade](/hyok/terraform#upgrade).
</Note>

<Steps>
  <Step title="See that an update is available">
    **Settings** → **Encryption** shows the installed and latest releases, with the latest release's label and changelog, under **Update available**.
  </Step>

  <Step title="Review the source diff">
    Open the diff in **Source audit** to see the files added, removed, and changed since your installed release. You can also [check the new release with the verification kit](/hyok/release-verification#level-2-check-and-rebuild-the-release-with-the-kit).
  </Step>

  <Step title="Click Upgrade stack">
    Corsa verifies the new release again (its digest, signature, and every file's SHA-256), then prepares the update for your workspace, your identity provider settings, and the new release. Your stack already authenticates to Corsa with its signing key, so there's no new callback token. Corsa records the upgrade as pending and opens the CloudFormation change set page for your stack, in its account and region.

    The link expires after a few hours. If it does, click **Upgrade stack** again.
  </Step>

  <Step title="Create the change set">
    Keep the existing parameter values and create the change set. Don't execute it yet.
  </Step>

  <Step title="Run the pre-upgrade check">
    Copy the pre-upgrade command from the app and run it in AWS CloudShell, in the stack's account and region. The check fails if the change set would replace your HYOK key, your stack's signing key, or your Cognito users. If the check fails, don't execute the change set. Delete it and contact Corsa. The stack's [built-in protection](/hyok/setup#protected-keys) blocks such a change anyway.
  </Step>

  <Step title="Execute the change set">
    Execute the change set in the console and wait for `UPDATE_COMPLETE`. The stack downloads the new release once and checks it before it installs anything.
  </Step>

  <Step title="Wait for completion">
    When the update finishes, the stack sends its signed details to Corsa. When the reported release digest matches the pending upgrade, **Settings** → **Encryption** shows the new release as installed. Any other digest shows as [release mismatch drift](#drift).
  </Step>

  <Step title="Verify">
    Run the [running-stack check](/hyok/release-verification#level-3-check-the-running-stack) for the new release, then open an encrypted field to confirm that decryption works.
  </Step>
</Steps>

An upgrade never replaces your keys or your Cognito users. Existing encrypted values, including values encrypted by earlier releases, keep decrypting after an upgrade.

### Roll back

**If the update fails,** CloudFormation rolls the stack back automatically. The stack keeps a copy of the previously installed release in your account and reinstalls it from there, without downloading anything. An expired release link can't block the rollback.

**If the update completed but you want the previous release back:**

<Steps>
  <Step title="Click Roll back">
    In **Settings** → **Encryption**, click **Roll back**. Corsa prepares an update to the release you ran immediately before the current one.
  </Step>

  <Step title="Check and execute the change set">
    Follow the same steps as an upgrade: create the change set, run the pre-upgrade check, and execute it. The stack restores the previous release from the copy it keeps in your account.
  </Step>

  <Step title="Verify">
    Run the running-stack check for the previous release digest.
  </Step>
</Steps>

You can roll back one release only. Corsa refuses to prepare an update to any older release.

***

## Health checks

Your stack exposes a public health endpoint. **Settings** → **Encryption** shows its URL. You can call it yourself:

```bash theme={null}
curl -i <your-health-url>
```

```json theme={null}
{
  "status": "ok",
  "checks": {
    "kms": true,
    "cognito": true,
    "oidc": null,
    "stackPolicy": true,
    "codeSigning": true
  },
  "releaseDigest": "9f2c…",
  "stackPolicySha256": "4b1e…",
  "identityProvider": "cognito",
  "timestamp": "2026-10-09T12:00:00.000Z"
}
```

| Field | Meaning |
| - | - |
| `status` | `ok` when every check that applies is `true`, `degraded` when any is `false` |
| `checks.kms` | Your HYOK key and the stack's signing key are enabled and usable |
| `checks.cognito` | Cognito sign-in is reachable. `null` when you use your own identity provider |
| `checks.oidc` | Your identity provider's issuer is reachable. `null` when you use Cognito |
| `checks.stackPolicy` | The stack's [built-in protection](/hyok/setup#protected-keys) for your keys and Cognito users is in place |
| `checks.codeSigning` | The stack only accepts [Corsa-signed code](/hyok/setup#signed-code-only) |
| `releaseDigest` | The release your stack runs |
| `stackPolicySha256` | A fingerprint of the stack's current protection settings. The **Verify** page shows the expected value |
| `identityProvider` | `cognito` or `oidc` |

The response carries `X-Corsa-Timestamp` and `X-Corsa-Signature` headers: an ECDSA-SHA256 signature by your stack's signing key over `<timestamp>.<body>`. Corsa polls the endpoint every 5 minutes, verifies the signature against the key your stack registered, and rejects responses more than 5 minutes old. The result appears in **Settings** → **Encryption** and as `healthStatus` and `lastHealthAt` in the [encryption configuration](/encryption/index#check-your-encryption-configuration). A `false` for `stackPolicy` or `codeSigning` also appears as [drift](#drift).

The health endpoint reveals no keys, users, or data.

***

## Drift

Corsa compares what your stack reports with what it expects and shows any difference as a drift badge in **Settings** → **Encryption**. Drift doesn't stop decryption. It tells you that your stack no longer matches the release and guardrails you installed.

| Drift | Meaning | What to do |
| - | - | - |
| Release mismatch (`release_mismatch`) | The stack reports a release digest that is neither your installed release nor a pending upgrade | Run the running-stack check. In CloudTrail, find who updated the stack. If nobody in your team made the change, treat it as a security incident. Then upgrade or roll back from the app to get back to a known release |
| Stack policy missing (`stack_policy_missing`) | The stack's built-in protection for your keys was removed or changed | In CloudTrail, find who changed it. Don't update the stack outside **Upgrade stack** or **Roll back** until it's fixed. The stack restores its protection during its next update. Contact Corsa if you need it restored sooner |
| Code signing off (`code_signing_off`) | The stack no longer refuses code that Corsa didn't sign | Run the running-stack check to see whether any code changed, and contact Corsa to restore the protection. If code changed, disable your HYOK key until you restore the release, and treat it as a security incident |
| Account mismatch (`account_mismatch`) | A stack reported its details from a different AWS account than the one you declared. Corsa rejected them | Deploy the stack in the declared account. See [Troubleshooting](/hyok/troubleshooting#setup-and-launch) |
| Region mismatch (`region_mismatch`) | A stack reported its details from a different region than the one you declared. Corsa rejected them | Deploy the stack in the declared region. See [Troubleshooting](/hyok/troubleshooting#setup-and-launch) |

***

## Control access to decryption

| Goal | Action in your AWS account or identity provider | Effect |
| - | - | - |
| Remove one person's access | With Cognito, remove them from `hyok-decryptors` or disable their Cognito user. With your own identity provider, remove them from the decryptor group or disable their account | Their next unwrap fails. With your own identity provider, tokens already issued stay valid until they expire |
| Pause all decryption (kill switch) | Disable your HYOK key in AWS KMS (`aws kms disable-key --key-id <your-hyok-key-arn>`). **Settings** → **Encryption** shows the key ARN | Nobody can decrypt, including your users. Health becomes `degraded`. Re-enable the key to resume |
| Investigate access | Read your stack's decryption audit log and the CloudTrail `Decrypt` events for your HYOK key. **Settings** → **Encryption** → **Review resources** shows where the audit log is | One audit line per unwrap: user, Corsa token ID, field, outcome |

While decryption is paused, Corsa keeps working on everything else. Exact search and exact-match screening also keep working, because they use the keyed index rather than decryption.

<Warning>
  Never schedule your HYOK key for deletion while HYOK data exists. Deleted keys can't be restored, and the data becomes permanently unreadable.
</Warning>

***

## Incident settings

Your stack has a few settings that Corsa may ask you to change during an incident, for example to keep older encrypted values readable. Change them only when Corsa support asks you to, and follow the instructions Corsa gives you. Leave them unchanged otherwise.


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