@dooer/dooer-test-env 1.15.0 → 1.16.0

package/docs/user-management.md

@@ -0,0 +1,246 @@
+# Logins and user management
+
+These commands talk to an environment through its **public GraphQL endpoint** — the same one the frontends
+use. No VPN, no kubectl, no cluster credentials: just an ordinary HTTPS call and a session.
+
+| environment | endpoint | `--env` |
+| --- | --- | --- |
+| your local stack | `http://localhost:4000/graphql` | `local` (the default) |
+| staging | `https://api.s-e032.com/graphql` | `staging`, or `dooer-staging` / `s-e032` |
+| live | `https://api.dooer.com/graphql` | `production`, or `live` / `dooer-production` |
+
+---
+
+## 1. The three kinds of user
+
+One person normally has **several user rows** — commonly `you@dooer.com` as a customer and
+`you+hi@dooer.com` as a professional. They are separate accounts with separate passwords, and *which one
+you sign in as* decides what you can see and do. This is the single most important thing on this page: most
+confusing "why can't I…" moments are a session that belongs to the wrong one of your accounts.
+
+| | who uses it | what it can see | how to log in |
+| --- | --- | --- | --- |
+| **customer** | end users | only the organizations attached to that user | email **or** BankID |
+| **partner** (`hi`) | accountants | every organization belonging to their partner | email **or** BankID |
+| **admin** | internal staff | everything, and can create users | email **only** |
+
+**BankID cannot reach an admin account.** The general BankID route (`loginWithBankIdV2`) is pinned to
+`user_type: 'customer'` in service-accounts, and the partner route resolves your `hi` account — so an admin
+session always comes from an email + password login.
+
+### Partners worth knowing
+
+A partner is an accounting firm; its `domain` is how it is addressed on the command line.
+
+| partner | domain | what it actually is |
+| --- | --- | --- |
+| Dooer | `dooer` | **Voitto** — the in-house accounting firm |
+| Dooer Sales | `dooersales` | **Dooer free customers** |
+
+`dooer-test-env partner list` shows the rest for whichever environment you point it at.
+
+---
+
+## 2. Logging in
+
+The session is stored in your macOS keychain, one per environment, and every other command picks it up.
+
+### As a customer user
+
+```bash
+# email + password (you are prompted for the password; it is not echoed)
+dooer-test-env remote-environment login --env staging --email you@dooer.com
+
+# BankID — --customer selects the customer route
+dooer-test-env remote-environment login --env staging --bankid --customer
+```
+
+### As a partner user (accountant)
+
+```bash
+# BankID — this is the default, and is exactly what HQ does
+dooer-test-env remote-environment login --env staging
+
+# email + password, using your professional account's address
+dooer-test-env remote-environment login --env staging --email you+hi@dooer.com
+```
+
+The BankID flow never asks which partner you are signing in to — like HQ, it submits an empty domain and
+lets the server resolve it from your BankID identity.
+
+### As an admin
+
+```bash
+dooer-test-env remote-environment login --env staging --email you+admin@dooer.com
+```
+
+Email only, for the reason in §1.
+
+### What a BankID login looks like
+
+An animated QR is drawn in the terminal and refreshed once a second (the payload is time-based, so a frozen
+QR stops scanning). Open the BankID app, scan, confirm — the command prints who you ended up as:
+
+```
+logged in to staging (s-e032) as Jimmy Bergman <jimmy.bergman+hi@dooer.com>
+  user id     203b9010-abb9-4f7c-9a5e-8bbf6f75ca7b
+  user type   hi
+  session     stored in keychain, valid until 2026-09-11T09:31:17.000Z
+```
+
+Always read the **user type** line. It is the quickest way to catch "I meant to be my other account".
+
+---
+
+## 3. Becoming a partner user from an admin session
+
+Signed in as an admin, you can assume a partner user without their BankID — the same thing back-office's
+**“Become user in X”** button does:
+
+```bash
+dooer-test-env remote-environment become someone+hi@dooer.com --env staging
+dooer-test-env remote-environment become someone+hi@dooer.com --env staging --partner "Dooer Sales"
+```
+
+`--partner` is only needed when they belong to more than one; otherwise it resolves on its own.
+
+Becoming replaces the stored session, so the admin token that authorised it is stashed first:
+
+```bash
+dooer-test-env remote-environment become --revert --env staging
+```
+
+---
+
+## 4. Who am I, and where
+
+```bash
+dooer-test-env remote-environment status --env staging
+dooer-test-env remote-environment status --all      # every environment at once
+dooer-test-env remote-environment list              # endpoints + whether you are logged in
+dooer-test-env remote-environment logout --env staging
+```
+
+---
+
+## 5. Using the token from scripts
+
+`remote-environment token` writes **only** the token to stdout — no colour, no label, no trailing text — so
+it drops straight into a variable or a pipe. Errors go to stderr, and stdout stays empty when they do.
+
+```bash
+dooer-test-env remote-environment token                      # local
+dooer-test-env remote-environment token --env staging
+dooer-test-env remote-environment token --env staging | pbcopy
+```
+
+Calling the API by hand with it:
+
+```bash
+TOKEN=$(dooer-test-env remote-environment token --env staging)
+
+curl -s https://api.s-e032.com/graphql \
+  -H "content-type: application/json" \
+  -H "authorization: Bearer $TOKEN" \
+  -d '{"query":"{ currentUser { id email userType } }"}'
+```
+
+The same works against the local stack on `http://localhost:4000/graphql`. The local environment needs no
+login at all — with no stored session it mints a service token from the shared dev keypair, so
+`token --env local` always returns something usable.
+
+> The token is a bearer credential for whichever account you logged in as. Treat it like a password: it is
+> fine in a shell variable, not in a commit, a ticket or a chat message.
+
+---
+
+## 6. Managing users
+
+```bash
+dooer-test-env user search                       # the most recent users
+dooer-test-env user search anna                  # email, name, personnummer or id
+dooer-test-env user search --role customer       # only customers
+dooer-test-env user get anna@dooer.com           # details + partner memberships
+dooer-test-env user partners anna@dooer.com      # just the memberships, with levels
+```
+
+Users are addressable by **id or email** everywhere.
+
+### Creating a user
+
+```bash
+# password generated and printed once
+dooer-test-env user create --email anna@dooer.com --execute
+
+# a customer, with your own password and a personnummer
+dooer-test-env user create --email kim@example.com \
+  --role customer --password 'hunter2hunter2' --personnummer 19900101-1239 --execute
+
+# a professional placed straight into a partner
+dooer-test-env user create --email anna@dooer.com --partner "Dooer Sales" --level admin --execute
+```
+
+This calls `users.create`, the same mutation back-office's `/users/new` uses, so the service hashes the
+password and applies its own validation. Notes:
+
+- **Needs an admin session** in any remote environment.
+- `--role` defaults to `hi`; the others are `customer` and `admin`.
+- The password is shown **once** and cannot be read back. It works on the ordinary email+password login.
+- First and last name default to something derived from the address; override with `--first-name` /
+  `--last-name`.
+- The personnummer must be a **real** one — the API checks the Luhn digit, so an invented number is
+  rejected. The CLI checks it first and tells you which rule failed.
+- Writes are **dry-run until `--execute`**.
+
+---
+
+## 7. Partner membership
+
+```bash
+dooer-test-env partner list                             # every partner in the environment
+dooer-test-env partner users "Dooer Sales"              # its users and their level
+
+dooer-test-env partner assign anna@dooer.com dooersales --level admin --execute
+dooer-test-env partner unassign anna@dooer.com dooersales --execute
+```
+
+Partners are addressable by **id, name or domain**.
+
+`--level` (`member` or `admin`) is the level *within* the partner — not the same axis as the user's
+`--role` at Dooer. Only **`hi`** users can belong to a partner; the CLI applies the same
+`invalid-user-type` rule the API does, so it will not write a row HQ would trip over.
+
+---
+
+## 8. What each session may do
+
+| operation | required session |
+| --- | --- |
+| `user search`, `user get`, `user partners` | any |
+| `partner assign`, `partner unassign`, `partner users` | partner |
+| `partner list` | admin |
+| `user create` | admin |
+
+When a session lacks the level, the CLI names the one that is required and who you are currently signed in
+as, instead of surfacing a raw `Forbidden`:
+
+```
+creating a user needs an "admin" session. You are signed in to staging as jimmy.bergman+hi@dooer.com (hi).
+
+  Log in as an account that has it:
+    dooer-test-env remote-environment login --env staging --email <your-admin-email>
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| `not logged in to <env>` | No session for that environment — log in (§2) |
+| `your <env> session expired …` | Sessions are short-lived; log in again |
+| `needs an "admin" session` | Wrong one of your accounts — see §1 and §8 |
+| `only "hi" users can belong to a partner` | You aimed a partner command at a customer/admin account |
+| `"x@y.com" matches N users` | That address exists once per user type; address the user by id instead |
+| `personnummer … has an invalid check digit` | Not a real personnummer — the API validates the Luhn digit |
+| BankID QR never completes on **local** | The local stack lost its BankID certs; `dooer-test-env up` re-injects them |

package/lib/command/remote-environment.js

@@ -204,6 +204,17 @@ module.exports = {
           console.log(`  Revert with: dooer-test-env remote-environment become --revert --env ${env.name}\n`)
         },
       })
+      .command({
+        command: 'token',
+        describe: 'print the stored token for an environment — bare, for scripts',
+        builder: envOption,
+        handler: (argv) => {
+          const env = remote.resolveEnv(argv.env)
+          // Deliberately the ONLY thing on stdout: no colour, no label, no trailing prose, so
+          // `$(… token)` and `| pbcopy` both do the obvious thing. Failures go to stderr via cli.js.
+          process.stdout.write(remote.tokenFor(env.name) + '\n')
+        },
+      })
       .command({
         command: 'status',
         describe: 'who you are logged in as, and until when',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooer/dooer-test-env",
-  "version": "1.15.0",
+  "version": "1.16.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",

package/readme.md

@@ -21,6 +21,9 @@ logins and the BankID cert all come from there.
   certificate, and verify both actually work.
 - **[Issuing access](./docs/issuing-access.md)** — admin: sign someone's certificate, bind their
   permissions, and revoke them again.
+- **[Logins and user management](./docs/user-management.md)** — signing in to an environment as a customer,
+  partner or admin user; creating users; partner membership; using the token from scripts. Needs no VPN or
+  kubectl at all.
 
 Already have both? Straight to the quick start.
 
@@ -53,7 +56,7 @@ db roles                                          (re)create per-service DB role
 db snapshot <name> | db rollback <name>          local restore points
 customer new "<name>" --owner <userId> --execute empty functional account: company + Owner + subscriptions + partner dooer
 customer copy | customer purge                    copy / delete one org between environments (emails anonymized)
-remote-environment login|become|status|logout|list  sign in to an environment; session → keychain
+remote-environment login|become|token|status|logout   sign in to an environment; session → keychain
 user search | get | create | partners             find/inspect/create users (local env unless --env)
 partner list | users | assign | unassign          partners and who belongs to them, at which level
 shred                                             anonymize the LOCAL db (localhost only)
@@ -167,57 +170,47 @@ user's `--role` at Dooer. Only **`hi`** users can belong to a partner; the CLI a
 
 ### Look at (or fix) users in a real environment
 
-The `user` and `partner` commands talk to an environment's **public GraphQL endpoint** — the same one the
-frontends use — so reaching staging or live needs no VPN, no kubectl and no cluster credentials. It does
-need a session. Sign in once per environment; the token is kept in your keychain:
+The `user` and `partner` commands reach an environment through its **public GraphQL endpoint** — the same
+one the frontends use — so staging and live need no VPN, no kubectl and no cluster credentials. They do
+need a session:
 
 ```bash
-# BankID — exactly what HQ does, so you get your professional (hi) account
+# BankID — what HQ does, so you get your professional (hi) account
 npx @dooer/dooer-test-env@latest remote-environment login --env staging
 
-# email + password (prompted, hidden) — the only way to reach an ADMIN account
+# email + password — the only route to an ADMIN account (BankID cannot reach one)
 npx @dooer/dooer-test-env@latest remote-environment login --env staging --email you+admin@dooer.com
 
-npx @dooer/dooer-test-env@latest remote-environment status --all   # who you are, in every environment
-npx @dooer/dooer-test-env@latest remote-environment logout --env staging
+npx @dooer/dooer-test-env@latest remote-environment status --all
 ```
 
-Then point any command at it with `--env` (`local` is the default; `staging`, `production`, and aliases
-like `dooer-staging` / `live` all resolve):
+Then point any command at it with `--env` (`local` is the default; `staging` / `production` and aliases
+like `dooer-staging` / `live` resolve too):
 
 ```bash
 npx @dooer/dooer-test-env@latest user search someone@dooer.com --env staging
 npx @dooer/dooer-test-env@latest partner list --env production
 ```
 
-**Which account you sign in as decides what you can do**, because one person has several user rows:
+**Which of your accounts you sign in as decides what you can do** — reads work from any session, partner
+membership needs a partner session, and creating a user needs an admin one. See
+**[Logins and user management](./docs/user-management.md)** for the full picture: the three kinds of user,
+`become`, and the permission matrix.
 
-| operation | needs | how to get it |
-| --- | --- | --- |
-| reads (`user search`, `user get`) | any session | either login |
-| `partner assign` / `unassign` | a **partner** session | BankID login, or `become` from an admin session |
-| `user create` | an **admin** session | password login as your admin account |
+### Use the session token in your own scripts
 
-BankID cannot reach an admin account at all: `loginWithBankIdV2` is pinned to `user_type: 'customer'`
-server-side, and HQ's partner flow resolves your `hi` user. When a session lacks the level, the CLI says
-which one is required and who you are currently signed in as, rather than surfacing a raw `Forbidden`.
-
-Signed in as an admin, you can assume a partner user without BankID — the same thing back-office's
-**“Become user in X”** button does (`partner.user.become`, itself admin-gated):
+`remote-environment token` prints the token and nothing else — no colour, no label — so it drops straight
+into a variable or a pipe:
 
 ```bash
-npx @dooer/dooer-test-env@latest remote-environment become someone@dooer.com --env staging
-# …--partner "Dooer Devteam" if they belong to more than one
+TOKEN=$(npx @dooer/dooer-test-env@latest remote-environment token --env staging)
 
-npx @dooer/dooer-test-env@latest remote-environment become --revert --env staging
+curl -s https://api.s-e032.com/graphql \
+  -H "content-type: application/json" -H "authorization: Bearer $TOKEN" \
+  -d '{"query":"{ currentUser { id email userType } }"}'
 ```
 
-Becoming replaces the stored session, so the admin token that authorised it is stashed first and
-`--revert` puts it back — otherwise you would have to log in again just to get where you were.
-
-The local env needs no login — it is signed with the shared dev keypair this CLI already holds.
-
-Writes are dry-run until `--execute`.
+The local env needs no login for this — with no stored session it mints one from the shared dev keypair.
 
 ### Copy a real customer into the local env