wcz-layout/skills/start/steps/07-vault-setup.md

# Vault Setup

Move the secrets that currently live in `.env.local` into Vault, then shrink
`.env.local` down to the Vault connection only.

Before starting, ask the user via **AskUserQuestion** which environment(s) to
set up: **QAS**, **PRD** or **both**. Both environments follow the same steps —
the login credentials, the Vault path (QAS lives under `sat-qas-01`, PRD under
`sat-prd-01`; each has its own Vault account and password) and a few
environment-specific payload values differ (see Part 2, step 0). When doing
both, run through Parts 1–2 once per environment. In Part 3, always write the
**QAS** connection into `.env.local` (if available).

To wait for something the user does in the browser — signing in, saving a
secret — poll in a tool loop: wait ~5 s, re-read the page, repeat until the
expected state appears or ~5 minutes pass, then carry straight on. Never end
your turn while waiting; announcing "I'll continue once you have signed in"
and stopping ends the session, and nothing resumes it.

Do not print secret values into chat, logs, or a commit — reference them by
key name. Values move from `.env.local` into the browser and nowhere else.

## Part 1 — Collect the payload from `.env.local`

1. Read `.env.local`. Note: it is typically gitignored, so glob/searches may not
   find it — read it directly by path. If it does not exist, create it. Also
   check `.env`: in the template repo some keys (e.g. `*_BASE_URL`) live there
   instead — include them in the payload too.
2. If `SESSION_SECRET` is empty or missing, generate one.
3. Build the JSON payload from every key in `.env.local` (except `DATABASE_AUTOMIGRATE`). A typical payload that goes to Vault.

   ```json
   {
     "ENTRA_CLIENT_ID": "...",
     "ENTRA_TENANT_ID": "...",
     "ENTRA_CLIENT_SECRET": "...",
     "SESSION_SECRET": "...",
     "DATABASE_URL": "..."
   }
   ```

## Part 2 — Write the secrets in the Vault UI

Repeat this part once per selected environment (QAS and/or PRD) — same steps,
different credentials and path.

0. Derive the environment-specific payload. The Part 1 payload reflects the
   local/QAS setup — before writing to a given environment, adjust these keys:
   - **`*_BASE_URL`** keys: if the host contains `qas` or `dev`, swap the
     environment segment for the target environment. The pattern is
     `https://<service>-api.wcz-sat-<env>-01.k8s.wistron.com`, e.g.
     `https://<service>-api.wcz-sat-qas-01.k8s.wistron.com` becomes
     `https://<service>-api.wcz-sat-prd-01.k8s.wistron.com`. Hosts that don't
     match this k8s pattern stay untouched. Do this automatically — never ask the user for these.
   - **`DATABASE_URL`**: the host is fixed per environment — QAS is always
     `10.82.36.60:5432`, PRD is always `10.82.36.50:5432`. Set the host
     automatically. The **username and password** cannot be derived: local
     usually uses `postgres`, but the provisioned per-app user is
     `wcz-<projectname>` with a **different password per environment** (QAS
     and PRD passwords differ). Ask the user for the target environment's DB
     info block (from the provisioning/WiCOP material, looks like
     `name: wcz-<project>-db / username: wcz-<project> / password: ...`) and
     substitute both username and password into the URL.
   - All other keys (`ENTRA_*`, `SESSION_SECRET`, ...) stay
     as-is.
1. Ask for the screenshot of WiCOP email or the **Vault path**, **Vault Account** and **Vault Password** one-by-one. The password is needed as a
   value in Part 3 (`VAULT_PASSWORD`), so it must be given in chat — do not
   have the user type it into the browser only. Note that **QAS and PRD live
   on different Vault hosts** (QAS is typically `vault-dev.wistron.com:8200`,
   PRD `vault-oss-prd.wistron.com:8200`) — the Vault path the user provides
   contains the right host; use it as-is.
2. Open the Vault address in the browser. Login with provided account and password and redirect to provided path:
   - The URL already contains the secret path, so it redirects there after login.
   - On the "Sign in to Vault" screen, open the **Method** dropdown and select **Userpass** (not the default Token).
   - Enter the **Username** (Vault Account), then the **Password**, then click **Sign in**.
   - You land on the secret list for the project path, e.g. `release/wcz/sat-<environment>-01/<project>-wcz`, containing a `default` secret.
3. Update the `default` secret with the derived environment payload from step 0:
   - Click the `default` secret to open it, then open the **Secret** tab.
   - Click **Create new version**.
   - Toggle the **JSON** switch in the toolbar, select all in the JSON editor (`Ctrl+A`) and replace it with the payload JSON from Part 1 (this also removes any pre-existing keys like `cog_test`).
   - Click **Save**. Verify the success toast "Successfully saved secret data" and that the new version lists every expected key.
4. Create the `harborvault` secret:
   - In the breadcrumb, click `<projectname>-wcz` to go one level up.
   - Click **Create secret**.
   - In **Path for this secret**, append `harborvault` to the pre-filled project path (i.e. `wcz/<env>/<projectname>-wcz/harborvault`).
   - Toggle the **JSON** switch, then ask the user to copy-paste the harborvault JSON from another project into the JSON editor (contains the `HARBOR_SECRET` key). The same JSON is used for both environments — it
     points to the shared PRD harbor registry (`wcz-sat-prd-harbor...`) even in
     QAS; that is intentional. Autonomously poll the editor until the content
     is there — do not end the session while waiting.
   - Click **Save**. Verify the success toast.
5. Close the Vault browser session.

## Part 3 — Rewrite `.env.local`

Use the **QAS** credentials here when both environments were set up.

Rewrite the file so it contains **only** these keys. Every app secret is now
served by Vault, so its local value is removed — a leftover value would
override Vault. `DATABASE_URL` stay filled because
drizzle-kit reads them directly and never goes through Vault.

`VAULT_SECRET_PATH` is the secret path **without** the mount point (`release`)
and **including** the trailing `/default` — the app builds
`/v1/<mount>/data/<VAULT_SECRET_PATH>` (see `src/lib/vite-plugin.ts`).
`VAULT_MOUNT_POINT` defaults to `release` and only needs to be set if the
engine is mounted elsewhere. If `VAULT_ADDRESS` is unset, Vault fetching is
skipped silently (plain local-dev fallback).

```dotenv
VAULT_ADDRESS=<scheme://host:port from Part 2, no path>
VAULT_SECRET_PATH=wcz/sat-qas-01/<project>-wcz/default
VAULT_USERNAME=<from Part 2>
VAULT_PASSWORD=<from Part 2>

DATABASE_URL=<kept — local dev DB or QAS, per user choice>
DATABASE_AUTOMIGRATE=<kept>
```

After writing, verify end-to-end: start the dev server (or replicate the
login + fetch from `src/lib/vite-plugin.ts`) and confirm all expected keys
come back from Vault.