@dooer/dooer-test-env 1.14.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/cli.js

@@ -6,25 +6,40 @@ const pkg = require('../package.json')
 // customers), copy/purge customers between environments, and shred — see ENVIRONMENT-PLAN.md.
 // Command groups are wired as modules under ./command.
 module.exports = async function cli() {
-  return yargs(hideBin(process.argv))
-    .scriptName('dooer-test-env')
-    .usage('$0 <group> <command> [options]')
-    .version(pkg.version)
-    .command(require('./command/setup')) // prerequisites + registry login + compose generation
-    .command(require('./command/env')) // up / down / start / stop / status
-    .command(require('./command/service')) // service start|stop|restart|deploy|local|unlocal|version
-    .command(require('./command/db')) // db build|pull|snapshot|rollback
-    .command(require('./command/customer')) // customer copy|purge
-    .command(require('./command/user')) // user search|get|create|partners
-    .command(require('./command/partner')) // partner list|users|assign|unassign
-    .command(require('./command/shred')) // shred (localhost only)
-    .command(require('./command/bankid')) // bankid pull|status|clear (staging certs → keychain)
-    .command(require('./command/validation')) // validation on|off|status (output-schema checks)
-    .command(require('./command/logs')) // search logs across all local services (transactionId, errors, …)
-    .command(require('./command/measure')) // resource-usage report for the running env
-    .demandCommand(1, 'Pick a command group. Try --help.')
-    .strict()
-    .help()
-    .wrap(Math.min(120, yargs().terminalWidth()))
-    .parseAsync()
+  return (
+    yargs(hideBin(process.argv))
+      .scriptName('dooer-test-env')
+      .usage('$0 <group> <command> [options]')
+      .version(pkg.version)
+      .command(require('./command/setup')) // prerequisites + registry login + compose generation
+      .command(require('./command/env')) // up / down / start / stop / status
+      .command(require('./command/service')) // service start|stop|restart|deploy|local|unlocal|version
+      .command(require('./command/db')) // db build|pull|snapshot|rollback
+      .command(require('./command/customer')) // customer copy|purge
+      .command(require('./command/remote-environment')) // login/status/logout/list against a public GraphQL API
+      .command(require('./command/user')) // user search|get|create|partners
+      .command(require('./command/partner')) // partner list|users|assign|unassign
+      .command(require('./command/shred')) // shred (localhost only)
+      .command(require('./command/bankid')) // bankid pull|status|clear (staging certs → keychain)
+      .command(require('./command/validation')) // validation on|off|status (output-schema checks)
+      .command(require('./command/logs')) // search logs across all local services (transactionId, errors, …)
+      .command(require('./command/measure')) // resource-usage report for the running env
+      .demandCommand(1, 'Pick a command group. Try --help.')
+      .strict()
+      // yargs prints the full usage block for a HANDLER failure too, which buries the actual message under
+      // an option list that has nothing to do with it (a permission error is not a usage error). Print the
+      // usage only when yargs itself rejected the arguments; otherwise just the message.
+      .fail((msg, err, yargsInstance) => {
+        if (!err) {
+          console.error(yargsInstance.help())
+          console.error(`\n${msg}\n`)
+        } else {
+          console.error(`\n${err.message}\n`)
+        }
+        process.exit(1)
+      })
+      .help()
+      .wrap(Math.min(120, yargs().terminalWidth()))
+      .parseAsync()
+  )
 }

package/lib/command/partner.js

@@ -1,6 +1,7 @@
 const chalk = require('chalk')
 const u = require('../users')
-const { targetOptions, writeOptions, label, printTable } = require('./target')
+const remote = require('../remote')
+const { envOption, writeOption, printTable } = require('./target')
 
 module.exports = {
   command: 'partner <command>',
@@ -10,17 +11,15 @@ module.exports = {
       .command({
         command: 'list',
         describe: 'list every partner in the environment',
-        builder: targetOptions,
+        builder: envOption,
         handler: async (argv) => {
-          const ns = u.targetOf(argv)
-          const rows = await u.withDb(ns, (db) => u.listPartners(db))
-          console.log(chalk.bold(`\n${rows.length} partner(s) in ${label(ns)}\n`))
+          const env = remote.resolveEnv(argv.env)
+          const rows = await u.listPartners(env)
+          console.log(chalk.bold(`\n${rows.length} partner(s) in ${env.label}\n`))
           printTable(rows, [
             ['NAME', (r) => r.name],
             ['DOMAIN', (r) => r.domain],
-            ['USERS', (r) => r.users],
             ['STATUS', (r) => r.status],
-            ['DEFAULT', (r) => (r.isDefaultPartner ? 'yes' : '')],
             ['ID', (r) => r.id],
           ])
           console.log()
@@ -30,29 +29,19 @@ module.exports = {
         command: 'users <partner>',
         describe: 'list the users of one partner and their level',
         builder: (y2) =>
-          targetOptions(y2).positional('partner', { type: 'string', describe: 'partner id, name or domain' }),
+          envOption(y2).positional('partner', { type: 'string', describe: 'partner id, name or domain' }),
         handler: async (argv) => {
-          const ns = u.targetOf(argv)
-          const { partner, rows } = await u.withDb(ns, async (db) => {
-            const partner = await u.findPartner(db, argv.partner)
-            const { rows } = await db.query(
-              `SELECT us.users_pk AS id, us.email, us.first_name, us.last_name,
-                      pu.role AS level, pu.status, pu."defaultRepresentative"
-               FROM "service_accounts"."partnerUser" pu
-               JOIN "service_accounts".users us ON us.users_pk = pu."userId"
-               WHERE pu."partnerId" = $1 ORDER BY us.email`,
-              [partner.id]
-            )
-            return { partner, rows }
-          })
-          console.log(chalk.bold(`\n${partner.name} — ${rows.length} user(s)`) + chalk.gray(`  (${label(ns)})\n`))
+          const env = remote.resolveEnv(argv.env)
+          const partner = await u.findPartner(env, argv.partner)
+          const rows = await u.partnerUsers(env, partner.id)
+          console.log(chalk.bold(`\n${partner.name} — ${rows.length} user(s)`) + `  (${env.label})\n`)
           printTable(rows, [
-            ['EMAIL', (r) => r.email],
-            ['NAME', (r) => `${r.first_name} ${r.last_name}`],
-            ['LEVEL', (r) => r.level],
+            ['EMAIL', (r) => r.user && r.user.email],
+            ['NAME', (r) => (r.user ? `${r.user.firstName} ${r.user.lastName}` : null)],
+            ['LEVEL', (r) => r.role],
             ['STATUS', (r) => r.status],
             ['DEFAULT REP', (r) => (r.defaultRepresentative ? 'yes' : 'no')],
-            ['ID', (r) => r.id],
+            ['ID', (r) => r.userId],
           ])
           console.log()
         },
@@ -61,31 +50,24 @@ module.exports = {
         command: 'assign <user> <partner>',
         describe: 'add a user to a partner (or change their level). Dry-run by default.',
         builder: (y2) =>
-          writeOptions(y2)
+          writeOption(envOption(y2))
             .positional('user', { type: 'string', describe: 'user id or email' })
             .positional('partner', { type: 'string', describe: 'partner id, name or domain' })
             .option('level', { choices: u.PARTNER_LEVELS, default: 'member', describe: 'level within the partner' }),
         handler: async (argv) => {
-          const ns = u.targetOf(argv)
-          u.guardWrite(ns, argv)
-          const { user, partner, res } = await u.withDb(ns, async (db) => {
-            const user = await u.findUser(db, argv.user)
-            const partner = await u.findPartner(db, argv.partner)
-            const res = await u.assignPartner(db, { user, partner, level: argv.level, execute: argv.execute })
-            return { user, partner, res }
-          })
-          const what =
-            res.previous && res.previous !== argv.level
-              ? `level ${res.previous} → ${argv.level}`
-              : res.previous
-              ? `already a ${argv.level} (no change)`
-              : `added as ${argv.level}`
+          const env = remote.resolveEnv(argv.env)
+          const user = await u.findUser(env, argv.user)
+          const partner = await u.findPartner(env, argv.partner)
+          // The API refuses a non-`hi` user (invalid-user-type); say so before spending a round trip.
+          if (user.userType !== 'hi') {
+            throw new Error(`only "hi" users can belong to a partner — ${user.email} is "${user.userType}"`)
+          }
+          if (argv.execute) await u.assignPartner(env, { userId: user.id, partnerId: partner.id, level: argv.level })
           console.log(
-            (argv.execute ? chalk.green('\n' + what) : chalk.yellow(`\nDRY RUN — would be ${what}`)) +
-              `: ${user.email} @ ${partner.name}` +
-              chalk.gray(`  (${label(ns)})`)
+            (argv.execute ? chalk.green(`\nset ${argv.level}`) : chalk.yellow(`\nDRY RUN — would set ${argv.level}`)) +
+              `: ${user.email} @ ${partner.name}  (${env.label})`
           )
-          if (!argv.execute) console.log(chalk.gray('  Re-run with --execute to apply.'))
+          if (!argv.execute) console.log('  Re-run with --execute to apply.')
           console.log()
         },
       })
@@ -93,24 +75,19 @@ module.exports = {
         command: 'unassign <user> <partner>',
         describe: 'remove a user from a partner. Dry-run by default.',
         builder: (y2) =>
-          writeOptions(y2)
+          writeOption(envOption(y2))
             .positional('user', { type: 'string', describe: 'user id or email' })
             .positional('partner', { type: 'string', describe: 'partner id, name or domain' }),
         handler: async (argv) => {
-          const ns = u.targetOf(argv)
-          u.guardWrite(ns, argv)
-          const { user, partner, res } = await u.withDb(ns, async (db) => {
-            const user = await u.findUser(db, argv.user)
-            const partner = await u.findPartner(db, argv.partner)
-            const res = await u.unassignPartner(db, { user, partner, execute: argv.execute })
-            return { user, partner, res }
-          })
+          const env = remote.resolveEnv(argv.env)
+          const user = await u.findUser(env, argv.user)
+          const partner = await u.findPartner(env, argv.partner)
+          if (argv.execute) await u.unassignPartner(env, { userId: user.id, partnerId: partner.id })
           console.log(
             (argv.execute ? chalk.green('\nremoved') : chalk.yellow('\nDRY RUN — would remove')) +
-              ` ${user.email} (${res.level}) from ${partner.name}` +
-              chalk.gray(`  (${label(ns)})`)
+              ` ${user.email} from ${partner.name}  (${env.label})`
           )
-          if (!argv.execute) console.log(chalk.gray('  Re-run with --execute to apply.'))
+          if (!argv.execute) console.log('  Re-run with --execute to apply.')
           console.log()
         },
       })