# Checking and rotating the secrets once tracked in git

`env-backend` and `env-frontend` were tracked in git until 6 Nov 2026 (removed in
backend `8fd8c46`). They are no longer in the code, but git history still holds
them. The GitHub repositories are private, so the exposure is anyone who has, or
had, access to a repository or a clone.

The file looks like a local one (`NODE_ENV=development`, the database host is
`localhost`). It still holds JWT secrets and AWS keys that look real. `env-frontend`
holds only the public API address and app name, so it needs nothing.

## 1. Check whether anything matches production

Run this on the production server, in `/home/ubuntu/hostelcare-backend`. It prints
fingerprints, so no secret reaches your screen or shell history.

```bash
for k in JWT_ACCESS_SECRET JWT_REFRESH_SECRET AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY; do
  now=$(grep "^$k=" .env | sed -E "s/^$k=//; s/^[\"']//; s/[\"']$//" | sha256sum | cut -c1-12)
  old=$(git show 8fd8c46~1:env-backend | grep "^$k=" | sed -E "s/^$k=//; s/^[\"']//; s/[\"']$//" | sha256sum | cut -c1-12)
  [ "$now" = "$old" ] && echo "$k: MATCHES, rotate" || echo "$k: different"
done
```

Also look up the AWS key in the IAM console, even if it differs from production. If
it is active on any account, deactivate it there.

## 2. Do this whatever the result

Set `MEDICAL_ENCRYPTION_KEY` before the first Enterprise tenant exists. It also seals
Enterprise government ID numbers. None of this data exists in production yet, so a new
key costs nothing now. If it stays unset, this data takes its key from
`JWT_REFRESH_SECRET`, and rotating that later would make it unreadable.

```bash
openssl rand -base64 32   # add to .env as MEDICAL_ENCRYPTION_KEY
```

Keep a copy somewhere safe outside the server. Losing this key loses the records.

## 3. If AWS keys match

No user impact.

1. Create a new access key in IAM.
2. Replace `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in `.env`.
3. Run `sudo pm2 restart hostelcare-api --update-env`.
4. Check that an upload and a download work.
5. Deactivate the old key, wait a day, then delete it.

## 4. If `JWT_ACCESS_SECRET` matches

Replace it and restart. Sessions recover by themselves through the refresh cookie,
and a CRM step-up in progress has to be repeated.

## 5. If `JWT_REFRESH_SECRET` matches

This secret does more than sign sessions, so pick a quiet time. It is also the key
behind the items below.

| Depends on it | What happens when it changes | What to do |
|---|---|---|
| Sessions | Everyone is signed out | Warn users beforehand |
| Authenticator app secrets | Unreadable, so those users can't sign in | **First** set `TOTP_ENCRYPTION_KEY` to the literal text `<old secret>:totp`, unless it is already set |
| Authenticator recovery codes | Stop working | Tell affected users to generate new ones. No setting preserves them |
| Medical records and Enterprise government ID numbers | Unreadable | Step 2 above |
| CRM unsubscribe links in emails already sent | Stop working | Handle any opt-out request by hand for a while. These links must keep working by law in some places, so consider a code change that accepts the old key too |
| Demo-booking links already sent | Stop working | Re-send to anyone with a demo booked |
| Trial sign-up codes and email sign-in codes in progress | Stop working | They expire soon anyway; users ask for a new one |
| Monthly feedback anonymous key | An employee could answer the current month's form twice | Rotate at the start of a month |

Order:

1. Set `TOTP_ENCRYPTION_KEY` and `MEDICAL_ENCRYPTION_KEY`, restart, and check that an
   authenticator sign-in still works.
2. Generate the new secret with `openssl rand -base64 48` and replace
   `JWT_REFRESH_SECRET`.
3. Restart with `sudo pm2 restart hostelcare-api --update-env`.
4. Check sign-in, including an account with an authenticator.

Keeping `TOTP_ENCRYPTION_KEY` at the old value means someone holding both the old
secret and a database copy could still read authenticator secrets. To close that,
re-encrypt those values under a new key. No script exists for this yet.

## 6. Git history

Rewriting history is not needed while the repositories stay private, and rotating is
what actually protects you. Rewrite with `git filter-repo` only if a repository may
become public; that needs a force push and every clone made again.

## Not checked

Nobody has yet compared these values with production. The commands above do that, and
they must be run by someone with server access.
