@dooer/dooer-test-env 1.12.0 → 1.13.0

package/docs/getting-access.md

@@ -6,7 +6,8 @@ fetch the BankID cert. That needs two things, in this order:
 1. **VPN** — the cluster API is not reachable from the open internet.
 2. **kubectl access** — a client certificate identifying you to the cluster.
 
-The VPN part is self-service. The kubectl part needs an admin to sign your certificate — see
+**Both come from an admin**: they create your VPN tunnel and your cluster credential, and send you two
+files — a WireGuard `.conf` and a `kubeconfig`. You install them and check they work. See
 [issuing-access.md](./issuing-access.md) for their side.
 
 ---
@@ -14,98 +15,50 @@ The VPN part is self-service. The kubectl part needs an admin to sign your certi
 ## 0. Prerequisites
 
 ```bash
-brew install wireguard-tools go jq kubernetes-cli
+brew install wireguard-tools kubernetes-cli
 ```
 
 `openssl` ships with macOS. Check everything is there:
 
 ```bash
-wg --version && go version && jq --version && kubectl version --client && openssl version
+wg --version && kubectl version --client && openssl version
 ```
 
 ---
 
 ## 1. VPN
 
-### 1a. Get a Robo10 token
+**Your admin creates the tunnel and sends you a `.conf` file.** You do not create it yourself and you do
+not need a Robo10 token for this — ask an admin, who follows
+[issuing-access.md § 1](./issuing-access.md#1-vpn--create-and-hand-over-a-tunnel).
 
-The VPN API is authenticated with a Robo10 access token. This opens a browser — **log in with your
-`@robo10.com` email**.
+The file they send you contains a **private key**. Treat it like a password: keep it out of chat, tickets
+and git, install it, and delete the copy they sent you.
 
-```bash
-TOKEN="$(go run github.com/strehle/cmdline-openid-client/openid-client@latest \
-  -issuer https://oidc-provider-backend.api.staging.roboten-dev.com \
-  -client_id ro_authentication_cl_id \
-  -port 34466 | awk '/===/ { if (start) nextfile; start = 1; next } start { print }' | jq -r .access_token)"
-
-[ -n "$TOKEN" ] && echo "token acquired" || echo "no token — did the browser login complete?"
-```
-
-Keep using **this same terminal** for the next steps: `$TOKEN` only exists in this shell.
-
-<details>
-<summary>Alternative if the Go client will not run</summary>
+### 1a. Install the config
 
-1. Open <https://chat.roboten.com> and log in.
-2. DevTools → **Application** → **Storage → Cookies**.
-3. Copy the value of the `x-op-token` cookie.
-4. In your terminal: `TOKEN=<the-cookie-value>`
-</details>
-
-### 1b. Create your tunnel
-
-One tunnel per person per machine. Name it after yourself so admins can tell them apart:
+`wg-quick` takes the interface name from the **filename**, so the name you pick here is the name you use in
+every later command. Check first what is already there — **do not overwrite an existing tunnel**:
 
 ```bash
-NAME="$(whoami)-$(hostname -s)"
-curl -sS -H "Authorization: Bearer $TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d "{ \"name\": \"$NAME\" }" \
-  https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
-```
-
-The response contains the tunnel's **id** — you need it next. To find it again later:
-
-```bash
-curl -sS -H "Authorization: Bearer $TOKEN" https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
-```
-
-### 1c. Download the tunnel config
-
-```bash
-ID=<the id from the previous step>
-curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
-  https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels/$ID/actions/get-config \
-  > ~/roboten.conf
+ls /opt/homebrew/etc/wireguard/
 ```
 
-> This file contains your **private key**. Treat it like a password: never commit it, never paste it into
-> chat or a ticket.
-
-### 1d. Install it
-
-`wg-quick` takes the interface name from the **filename**, so the name you choose here is the name you use
-in every later command. Pick something that will not collide with a tunnel you already have:
+Then install it (using `roboten` as the interface name):
 
 ```bash
 sudo mkdir -p /opt/homebrew/etc/wireguard
-sudo cp ~/roboten.conf /opt/homebrew/etc/wireguard/roboten.conf
+sudo cp ~/Downloads/<the-file-they-sent>.conf /opt/homebrew/etc/wireguard/roboten.conf
 sudo chmod 600 /opt/homebrew/etc/wireguard/roboten.conf
-rm ~/roboten.conf          # the copy under /opt/homebrew is the one wg-quick reads
+rm ~/Downloads/<the-file-they-sent>.conf     # the copy under /opt/homebrew is the one wg-quick reads
 ```
 
-Check first whether that name is already taken — **do not overwrite someone else's tunnel**:
-
-```bash
-ls /opt/homebrew/etc/wireguard/
-```
-
-### 1e. Connect, disconnect, restart
+### 1b. Connect, disconnect, restart
 
 ```bash
 sudo wg-quick up roboten       # connect
 sudo wg-quick down roboten     # disconnect
-sudo wg-quick down roboten && sudo wg-quick up roboten   # restart (after a config change or a sleep/wake)
+sudo wg-quick down roboten && sudo wg-quick up roboten   # restart (after a config change or sleep/wake)
 
 sudo wg show                   # status: handshake time + transfer counters
 ```
@@ -122,75 +75,59 @@ sudo brew services start wireguard-tools   # starts wg0 by default
 
 That service is hard-wired to the `wg0` interface, so it only helps if you named your file `wg0.conf`.
 
-### 1f. Verify the VPN works
+### 1c. Verify the VPN works
 
 ```bash
 sudo wg show                                    # expect a recent "latest handshake"
 nc -vz k8s.roboten-infra.com 64430              # expect: succeeded / open
 ```
 
-If `nc` hangs or is refused, the tunnel is not carrying traffic — restart it (1e). Until this passes, no
+If `nc` hangs or is refused, the tunnel is not carrying traffic — restart it (1b). Until this passes, no
 amount of kubectl configuration will help.
 
+> The tunnel routes the cluster network (including the API server) through WireGuard. If you already have
+> another VPN claiming those ranges, they will fight over the routes — bring only one up at a time.
+
 ---
 
 ## 2. kubectl access
 
-Authentication is a **client certificate**. You generate the key and the signing request; only the request
-leaves your machine. Your private key never does.
+**Your admin sends you a ready-made `kubeconfig` file.** You do not generate keys or assemble anything —
+they create the credential and hand it over
+([issuing-access.md § 2](./issuing-access.md#2-kubectl--create-their-credential)).
 
-### 2a. Generate your key and CSR
+Like the VPN config, that file contains a **private key**. Same handling: install it, then delete the copy
+they sent you.
 
-Use `<firstname>-admin` as the name — that string becomes your username in the cluster, and it is what the
-admin binds permissions to.
+### 2a. Install it
 
-```bash
-USER_NAME=<firstname>-admin
-mkdir -p ~/.kube/roboten && cd ~/.kube/roboten
+**If you have no other clusters** — simplest, just put it in place:
 
-openssl genrsa -out "$USER_NAME.key" 2048
-openssl req -new -key "$USER_NAME.key" -out "$USER_NAME.csr" -subj "/CN=$USER_NAME"
-chmod 600 "$USER_NAME.key"
+```bash
+mkdir -p ~/.kube
+cp ~/Downloads/<yourname>.kubeconfig ~/.kube/config
+chmod 600 ~/.kube/config
+rm ~/Downloads/<yourname>.kubeconfig
 ```
 
-### 2b. Send the CSR to an admin
-
-Send **only** `<firstname>-admin.csr`. It is not secret — but the `.key` next to it is, and must never
-leave your machine.
-
-Ask them for three things back:
-
-| | |
-| --- | --- |
-| `<firstname>-admin.crt` | your signed certificate |
-| `ca.crt` | the cluster CA certificate |
-| the API server URL | currently `https://k8s.roboten-infra.com:64430` |
-
-### 2c. Assemble your kubeconfig
-
-Put the two `.crt` files next to your key in `~/.kube/roboten`, then:
+**If you already use kubectl for something else**, merge instead of overwriting:
 
 ```bash
-cd ~/.kube/roboten
-USER_NAME=<firstname>-admin
-SERVER=https://k8s.roboten-infra.com:64430
-
-KUBECONFIG=~/.kube/config kubectl config set-cluster kubernetes \
-  --server="$SERVER" --certificate-authority=ca.crt --embed-certs=true
-
-KUBECONFIG=~/.kube/config kubectl config set-credentials "$USER_NAME" \
-  --client-certificate="$USER_NAME.crt" --client-key="$USER_NAME.key" --embed-certs=true
+cp ~/.kube/config ~/.kube/config.backup            # always back up first
+KUBECONFIG=~/.kube/config:~/Downloads/<yourname>.kubeconfig \
+  kubectl config view --flatten > /tmp/merged && mv /tmp/merged ~/.kube/config
+chmod 600 ~/.kube/config
+rm ~/Downloads/<yourname>.kubeconfig
+```
 
-KUBECONFIG=~/.kube/config kubectl config set-context "$USER_NAME@kubernetes" \
-  --cluster=kubernetes --user="$USER_NAME"
+Then select the context (the admin will tell you its name, `<firstname>-admin@kubernetes`):
 
-KUBECONFIG=~/.kube/config kubectl config use-context "$USER_NAME@kubernetes"
+```bash
+kubectl config get-contexts
+kubectl config use-context <firstname>-admin@kubernetes
 ```
 
-`--embed-certs=true` copies the certificates *into* `~/.kube/config`, so the files in `~/.kube/roboten` are
-only a backup after this point. Keep the `.key` anyway — you need it if you ever rebuild the config.
-
-### 2d. Verify
+### 2b. Verify
 
 With the VPN up:
 
@@ -228,12 +165,11 @@ npx @dooer/dooer-test-env@latest setup
 
 | Symptom | Cause |
 | --- | --- |
-| `dial tcp … i/o timeout` from kubectl | VPN is down — `sudo wg show`, then restart it (1e) |
+| `dial tcp … i/o timeout` from kubectl | VPN is down — `sudo wg show`, then restart it (1b) |
 | `nc` to the API server hangs | Tunnel is up but not carrying traffic; restart it |
-| `error: You must be logged in to the server (Unauthorized)` | Certificate is wrong/expired, or the cluster does not know that CN — back to 2b |
-| `Error from server (Forbidden)` | You *are* authenticated; your user has no permissions bound yet — ask the admin to complete their step 3 |
-| `no token — did the browser login complete?` | The OIDC flow did not finish; make sure you used your `@robo10.com` account |
+| `error: You must be logged in to the server (Unauthorized)` | The certificate in your kubeconfig is expired or unknown to the cluster — ask for a re-issue |
+| `Error from server (Forbidden)` | You *are* authenticated; your user has no permissions bound yet — ask the admin to complete their § 2e (bind permissions) |
 | `wg-quick: 'roboten' already exists` | The interface is already up — `sudo wg-quick down roboten` first |
 
-Certificates are issued for **one year**. When yours expires you repeat section 2 — the admin only has to
-re-sign; your permissions (step 3 on their side) stay in place.
+Certificates are issued for **one year**. When yours expires, ask your admin for a new kubeconfig and
+repeat section 2 — your permissions stay in place, so they only have to re-issue the credential.

package/docs/issuing-access.md

@@ -4,66 +4,133 @@ The other side of [getting-access.md](./getting-access.md). Two independent thin
 
 | | Who does it | What you do |
 | --- | --- | --- |
-| **VPN tunnel** | self-service | make sure they have a Robo10 login; nothing to hand out |
-| **kubectl credential** | needs you | sign their CSR and bind their permissions |
+| **VPN tunnel** | you | create it and send them the config |
+| **kubectl credential** | you | create the certificate, bind permissions, send a kubeconfig |
 
-You need `kubectl` with cluster-admin (`system:masters`) and the VPN up.
+You need a Robo10 token (§1a), `kubectl` with cluster-admin (`system:masters`), and your own VPN up.
 
 ---
 
-## 1. VPN — what you actually have to do
+## 1. VPN — create and hand over a tunnel
 
-Tunnels are **self-service**: any valid Robo10 token can create one, and the config is generated on demand
-by the VPN API. So there is no artefact for you to produce or send.
+You create the tunnel and send the developer its config. They do not need a Robo10 token, which matters:
+a brand-new joiner often has no working login yet, and the VPN API generates the keypair **server-side**
+anyway — the config comes back with the private key in it either way, so there is no custody advantage to
+making them do it.
 
-Your only job is to make sure the person can log in at <https://chat.roboten.com> with their
-**`@robo10.com`** account — that same identity is what the token flow authenticates. If they cannot log in,
-that is an account-provisioning issue in Robo10, not something this guide covers.
+### 1a. Get a Robo10 token (yours)
+
+Opens a browser — log in with **your `@robo10.com` account**:
+
+```bash
+TOKEN="$(go run github.com/strehle/cmdline-openid-client/openid-client@latest \
+  -issuer https://oidc-provider-backend.api.staging.roboten-dev.com \
+  -client_id ro_authentication_cl_id \
+  -port 34466 | awk '/===/ { if (start) nextfile; start = 1; next } start { print }' | jq -r .access_token)"
+
+[ -n "$TOKEN" ] && echo "token acquired" || echo "no token — did the browser login complete?"
+```
+
+Needs `go` and `jq` (`brew install go jq`). Keep using **this same terminal**: `$TOKEN` lives only in this
+shell, and everything below needs it.
+
+<details>
+<summary>Alternative if the Go client will not run</summary>
+
+1. Open <https://chat.roboten.com> and log in.
+2. DevTools → **Application** → **Storage → Cookies**.
+3. Copy the value of the `x-op-token` cookie.
+4. In your terminal: `TOKEN=<the-cookie-value>`
+</details>
+
+### 1b. Create their tunnel
+
+Name it after the person (and their machine if they need more than one) so the list stays readable:
+
+```bash
+NAME="Firstname Lastname"
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d "{ \"name\": \"$NAME\" }" \
+  https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
+```
+
+The response contains the tunnel's **id**. To find it again later, list them (1d).
+
+### 1c. Download the config and hand it over
+
+```bash
+ID=<the id from the previous step>
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
+  https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels/$ID/actions/get-config \
+  > ~/Downloads/$NAME.conf
+```
+
+> **This file contains a private key.** Send it over a channel you would send a password over — a shared
+> vault entry or an expiring secure link — not email, Slack or a ticket. Tell them to install it and delete
+> the copy you sent, and delete your own copy once they confirm.
 
 Then point them at [getting-access.md § 1](./getting-access.md#1-vpn).
 
-**Never** create the tunnel on their behalf and send them the config: the config embeds a private key, so a
-tunnel they generated themselves is the only one only they hold.
+One tunnel per person per machine: two devices sharing one config will fight over the session, so create a
+second tunnel rather than re-sending the first.
 
-To see who has tunnels (with your own token, as in the dev guide):
+### 1d. List tunnels
 
 ```bash
 curl -sS -H "Authorization: Bearer $TOKEN" https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
 ```
 
-To revoke one — `DELETE` is not in the VPN service's own docs, but it works (verified 2026-09-04, returns
-`204` and the tunnel disappears from the list):
+### 1e. Revoke a tunnel
+
+`DELETE` is not in the VPN service's own docs, but it works (verified 2026-09-04 — returns `204` and the
+tunnel disappears from the list):
 
 ```bash
 curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" \
   https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels/$ID
 ```
 
-That invalidates the tunnel's key server-side, so it is the real off-switch for VPN access when someone
-leaves — do it *and* revoke their kubectl permissions (§3).
+That invalidates the tunnel server-side, so it is the real off-switch for VPN access when someone leaves —
+do it *and* revoke their kubectl permissions (§3).
 
 ---
 
-## 2. kubectl — sign their certificate
+## 2. kubectl — create their credential
 
 The cluster authenticates users with **x509 client certificates** signed by the cluster CA. The username is
 the certificate's **Common Name (CN)**; RBAC is bound to that string.
 
-You never see their private key. They send you a `.csr`; you send back a `.crt`.
+You do all of it and hand over a finished `kubeconfig`.
 
-### 2a. Submit their CSR to the cluster
+> Everything below was verified end to end against the live cluster (2026-09-04) with a throwaway
+> `guidetest-admin`: the resulting kubeconfig read `dooer-production` and `dooer-staging`, including
+> secrets. The test user was then removed.
 
 ```bash
-USER_NAME=<firstname>-admin          # must match the CN in their CSR
-CSR_FILE=~/Downloads/$USER_NAME.csr  # what they sent you
+USER_NAME=<firstname>-admin        # becomes their cluster username
+WORKDIR=$(mktemp -d) && cd "$WORKDIR"
+```
 
+Work in a temp directory — it holds their private key until you hand it over, and you delete it at the end.
+
+### 2a. Generate their key and CSR
+
+```bash
+openssl genrsa -out "$USER_NAME.key" 2048
+openssl req -new -key "$USER_NAME.key" -out "$USER_NAME.csr" -subj "/CN=$USER_NAME"
+```
+
+### 2b. Submit it as a CertificateSigningRequest
+
+```bash
 cat <<EOF | kubectl apply -f -
 apiVersion: certificates.k8s.io/v1
 kind: CertificateSigningRequest
 metadata:
   name: $USER_NAME
 spec:
-  request: $(base64 -i "$CSR_FILE" | tr -d '\n')
+  request: $(base64 -i "$USER_NAME.csr" | tr -d '\n')
   signerName: kubernetes.io/kube-apiserver-client
   expirationSeconds: 31536000   # 1 year
   usages:
@@ -71,15 +138,10 @@ spec:
 EOF
 ```
 
-Sanity-check the CN is what you expect before approving — the CN is the identity you are about to grant
-admin to:
-
-```bash
-openssl req -in "$CSR_FILE" -noout -subject
-# subject=CN=<firstname>-admin
-```
+If the name already exists (a renewal), delete the old object first:
+`kubectl delete csr "$USER_NAME" --ignore-not-found`.
 
-### 2b. Approve and extract the certificate
+### 2c. Approve and extract the certificate
 
 ```bash
 kubectl certificate approve "$USER_NAME"
@@ -90,18 +152,16 @@ openssl x509 -in "$USER_NAME.crt" -noout -subject -issuer -dates
 
 Expect `subject=CN=<firstname>-admin`, `issuer=CN=kubernetes`, and a one-year window.
 
-If `.status.certificate` is empty, the signer has not run yet — wait a couple of seconds and repeat. If it
-stays empty, the CSR was approved but not signed; check `kubectl describe csr "$USER_NAME"`.
-
-### 2c. Extract the cluster CA
+If `.status.certificate` is empty the signer has not run yet — wait a couple of seconds and repeat. If it
+stays empty, check `kubectl describe csr "$USER_NAME"`.
 
-The same file for everyone:
+### 2d. Extract the cluster CA
 
 ```bash
 kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt
 ```
 
-### 2d. Bind permissions
+### 2e. Bind permissions
 
 This is what makes the certificate useful — without it they authenticate but can do nothing. These are the
 same five ClusterRoles the existing admins (`jimmy-admin`, `sam-admin`, `trajko-admin`) hold:
@@ -125,25 +185,54 @@ The declarative equivalent lives in
 is enough for the cluster, but that file is the record of who has access — **add the new user there and
 commit it**, or the next person reading it will get a false picture.
 
-### 2e. Hand back
+On a renewal, skip this step: the bindings are attached to the username, not to the certificate.
+
+### 2f. Assemble the kubeconfig
 
-Send them three things (none are secret — the secret half never left their machine):
+`--embed-certs=true` inlines the key and certificates, so the file you hand over is self-contained:
 
-1. `<firstname>-admin.crt`
-2. `ca.crt`
-3. the API server URL — currently `https://k8s.roboten-infra.com:64430`
+```bash
+SERVER=https://k8s.roboten-infra.com:64430
+KC="$WORKDIR/$USER_NAME.kubeconfig"
+
+KUBECONFIG="$KC" kubectl config set-cluster kubernetes \
+  --server="$SERVER" --certificate-authority=ca.crt --embed-certs=true
 
-Then they follow [getting-access.md § 2c](./getting-access.md#2c-assemble-your-kubeconfig).
+KUBECONFIG="$KC" kubectl config set-credentials "$USER_NAME" \
+  --client-certificate="$USER_NAME.crt" --client-key="$USER_NAME.key" --embed-certs=true
 
-### 2f. Verify before you tell them it is done
+KUBECONFIG="$KC" kubectl config set-context "$USER_NAME@kubernetes" \
+  --cluster=kubernetes --user="$USER_NAME"
+
+KUBECONFIG="$KC" kubectl config use-context "$USER_NAME@kubernetes"
+```
+
+### 2g. Verify it before handing it over
+
+Test the actual file, not just the RBAC — with your own VPN up:
 
 ```bash
-kubectl get clusterrolebinding | grep "$USER_NAME"     # expect 5 rows
-kubectl auth can-i get pods -n dooer-production --as "$USER_NAME"
-kubectl auth can-i get secrets -n dooer-staging --as "$USER_NAME"
+KUBECONFIG="$KC" kubectl auth whoami                                  # Username: <firstname>-admin
+KUBECONFIG="$KC" kubectl get pods -n dooer-staging | head -3
+KUBECONFIG="$KC" kubectl get pods -n dooer-production | head -3
+KUBECONFIG="$KC" kubectl auth can-i get secrets -n dooer-staging      # yes
 ```
 
-`--as` impersonates the user, so you are testing the real RBAC without needing their certificate.
+If `whoami` works but the reads say `Forbidden`, step 2e did not take.
+
+### 2h. Hand it over, then clean up
+
+> **The kubeconfig contains their private key.** Send it the same way as the VPN config — a shared vault
+> entry or an expiring secure link, never email, Slack or a ticket.
+
+Tell them the context name (`<firstname>-admin@kubernetes`) and point them at
+[getting-access.md § 2](./getting-access.md#2-kubectl-access).
+
+Once they confirm it works, destroy your copy — you are holding their key until you do:
+
+```bash
+rm -rf "$WORKDIR"
+```
 
 ---
 
@@ -169,9 +258,11 @@ Also remove them from `clusterrole-admin.yaml` and commit.
 
 ## Renewals
 
-A certificate expiring is routine: the user repeats [getting-access.md § 2a–2c](./getting-access.md#2a-generate-your-key-and-csr)
-and you repeat **2a–2c and 2e** here. Skip 2d — their ClusterRoleBindings are bound to the username, not to
-the certificate, so they survive a re-issue untouched.
+A certificate expiring is routine. Repeat **§2a–2d and 2f–2h** and send them a fresh kubeconfig; they
+re-run [getting-access.md § 2](./getting-access.md#2-kubectl-access).
+
+Skip **2e** — ClusterRoleBindings are bound to the username, not to the certificate, so they survive a
+re-issue untouched.
 
 Delete the old CSR object first, or the new one collides on the name:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooer/dooer-test-env",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Run the whole Dooer backend locally (staging DB minus customers), copy/purge customers between environments, and shred — one CLI.",
   "license": "UNLICENSED",
   "repository": "Dooer/cli-dooer-test-env",