@dooer/dooer-test-env 1.14.0 → 1.16.0

package/lib/users.js

@@ -1,56 +1,25 @@
-// users.js — user + partner-membership operations against a target environment (the local env by
-// default, or any k8s namespace). Reads and writes go straight to the service_accounts schema over the
-// same self-healing connection the copy engine uses (lib/engine/seed.js `connect`), which already knows
-// how to reach both the local Postgres and a namespace's dooer-database.
+// users.js — user and partner-membership operations against any environment, over its PUBLIC GraphQL
+// endpoint (see lib/remote.js). No SQL, no kubectl: these are the same mutations the products call, so
+// every rule the API enforces — input validation, password hashing, the `hi`-only partner check — applies
+// here for free rather than being reimplemented and drifting.
 //
-// Why SQL and not the service-accounts HTTP API:
-//   * there is NO user-create route at all — users only ever appear via the signup flows, which also
-//     create a company; that is exactly what we do NOT want here.
-//   * nothing subscribes to a user-created event (checked across every service's eventStream.handle),
-//     so a plain INSERT leaves no consumer un-notified. Contrast `customer new`, which goes through the
-//     ledger API precisely because service-closing builds its periods off the emitted event.
-//   * the partner-membership route (PUT /v1/partners/:partnerId/users/:userId) is a bare upsert with one
-//     guard — the user must be of type `hi`. We reproduce that guard below rather than dropping it, so
-//     the CLI cannot create rows the product would have refused.
+//   users.create            back-office /users/new (UsersMutation.create → POST /v1/users)
+//   partner.users.set       PartnerUsersMutation.set → PUT /v1/partners/:id/users/:userId
+//   partner.user.delete     PartnerUserMutation.delete
 const crypto = require('crypto')
-const bcrypt = require('bcryptjs')
-const { connect } = require('./engine/seed')
+const remote = require('./remote')
 
-const SCHEMA = 'service_accounts'
-const T_USERS = `"${SCHEMA}".users`
-const T_PARTNER = `"${SCHEMA}".partner`
-const T_PARTNER_USER = `"${SCHEMA}"."partnerUser"`
-
-// service_accounts.user_roles_at_dooer. `hi` = the accounting-professional user a partner can employ;
-// `hiab` exists in the table but is legacy — not offered as a choice.
+// service_accounts.user_roles_at_dooer, as exposed by the GraphQL UserType enum. `hiab` exists in the
+// table but is legacy — not offered as a choice.
 const USER_ROLES = ['hi', 'customer', 'admin']
-// service_accounts."partnerUser_role_enum" — the "level" within a partner.
+// PartnerUserRole — the "level" within a partner, distinct from the user's role at Dooer.
 const PARTNER_LEVELS = ['member', 'admin']
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
-// ── target environment ───────────────────────────────────────────────────────
-// Default is the LOCAL env. `local` is a pseudo-namespace inside the engine, not a k8s one, so it is
-// addressed with --target-local and rejected as a --target-namespace value (same split as customer copy).
-function targetOf(argv) {
-  if (argv.targetNamespace === 'local') {
-    throw new Error('use --target-local for the local env, not --target-namespace local')
-  }
-  if (argv.targetLocal && argv.targetNamespace) {
-    throw new Error('pass either --target-local or --target-namespace, not both')
-  }
-  return argv.targetNamespace || 'local'
-}
-
-// Writing users into the production cluster is possible but must never be a slip of the shell.
-function guardWrite(namespace, argv) {
-  if (namespace === 'dooer-production' && !argv.confirmProduction) {
-    throw new Error('refusing to write to dooer-production without --confirm-production')
-  }
-}
-
 // ── password ────────────────────────────────────────────────────────────────
 // Ambiguous glyphs (0/O, 1/l/I) are left out — these get read off a screen and typed into a login form.
+// The service hashes it; this CLI never sees a hash.
 const ALPHABET = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ23456789'
 
 function generatePassword(groups = 4, size = 5) {
@@ -58,228 +27,253 @@ function generatePassword(groups = 4, size = 5) {
   return Array.from({ length: groups }, chunk).join('-')
 }
 
-// service-accounts' own rule (lib/verify-password.js) is length >= 8 and nothing else; enforce exactly
-// that so a password this CLI accepts is a password the login accepts.
-function hashPassword(password) {
-  if (password.length < 8) throw new Error('password must be at least 8 characters (service-accounts rule)')
-  // bcryptjs, not bcrypt: identical wire format, but pure JS — a native build would break `npx`.
-  // get-login-user.js rewrites a stored `$2b$` prefix to `$2a$` before comparing, so either emits fine.
-  return bcrypt.hashSync(password, 10)
+// ── personnummer ────────────────────────────────────────────────────────────
+// The API's `SwedishPersonalIdentificationNumber` scalar wants 12 bare digits AND a correct Luhn check
+// digit over the last 10 (@dooer/json-validator: is-my-svenskt-personnummer-valid). Checking both here
+// turns "is not svenskt-personnummer format" — a GraphQL variable-coercion dump that does not say WHICH
+// rule failed — into a sentence, and catches an invented number before it costs a round trip.
+function luhnOk(tenDigits) {
+  let sum = 0
+  for (let i = 0; i < 10; i++) {
+    const double = i % 2 === 0
+    let d = Number(tenDigits[i]) * (double ? 2 : 1)
+    if (d > 9) d -= 9
+    sum += d
+  }
+  return sum % 10 === 0
 }
 
-// ── personnummer ────────────────────────────────────────────────────────────
-// Stored as 12 bare digits (verified against staging: every non-null id_number is length 12).
 function normalizePersonnummer(input) {
   const digits = String(input).replace(/\D/g, '')
-  if (digits.length === 12) return digits
-  if (digits.length === 10) {
-    // YY > current two-digit year means last century — the usual short-form expansion.
+  let full
+  if (digits.length === 12) full = digits
+  else if (digits.length === 10) {
+    // YY greater than the current two-digit year means last century — the usual short-form expansion.
     const yy = Number(digits.slice(0, 2))
-    const nowYY = new Date().getFullYear() % 100
-    return (yy > nowYY ? '19' : '20') + digits
+    full = (yy > new Date().getFullYear() % 100 ? '19' : '20') + digits
+  } else {
+    throw new Error(`personnummer must be 10 or 12 digits (got ${digits.length}): ${input}`)
+  }
+  const [, m, d] = /^\d{4}(\d{2})(\d{2})/.exec(full)
+  if (Number.isNaN(Date.parse(`${full.slice(0, 4)}-${m}-${d}`))) {
+    throw new Error(`personnummer ${full} is not a real date`)
+  }
+  if (!luhnOk(full.slice(2))) {
+    throw new Error(
+      `personnummer ${full} has an invalid check digit — the API validates it, so an invented number is rejected`
+    )
   }
-  throw new Error(`personnummer must be 10 or 12 digits (got ${digits.length}): ${input}`)
+  return full
 }
 
 // ── name defaults ───────────────────────────────────────────────────────────
-// first_name/last_name are NOT NULL with no default. Derive something sane from the address so the
-// common case is just `--email`.
+// firstName/lastName are required by UserInput; derive something sane so the common case is just --email.
 function namesFromEmail(email) {
-  const local = email.split('@')[0]
-  const parts = local.split(/[._-]+/).filter(Boolean)
+  const parts = email
+    .split('@')[0]
+    .split(/[._+-]+/)
+    .filter(Boolean)
   const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1)
-  return {
-    firstName: cap(parts[0] || 'Test'),
-    lastName: cap(parts.slice(1).join(' ') || 'User'),
+  return { firstName: cap(parts[0] || 'Test'), lastName: cap(parts.slice(1).join(' ') || 'User') }
+}
+
+// ── permission errors ───────────────────────────────────────────────────────
+// A denial comes back as `Forbidden: No access allowed for resource 'admin:<uuid>'`, which says nothing
+// about what to do next. Rewrite it into the actual problem: this operation needs a different one of your
+// accounts than the one you are signed in as.
+//
+// The branch is on the server's STRUCTURED `extra.resourceType`, not on the prose — the sentence is a
+// human-facing string that can be reworded, and matching it would silently stop working when it is.
+async function withLevel(env, need, fn) {
+  try {
+    return await fn()
+  } catch (e) {
+    const required = e.code === 'forbidden' ? e.resourceType : null
+    if (!required) throw e
+    let asWho = ''
+    try {
+      const me = await remote.currentUser(env)
+      if (me) asWho = ` You are signed in to ${env.name} as ${me.email} (${me.userType}).`
+    } catch (_) {
+      /* whoami is a nicety; never let it mask the real error */
+    }
+    const how =
+      required === 'admin'
+        ? `dooer-test-env remote-environment login --env ${env.name} --email <your-admin-email>`
+        : `dooer-test-env remote-environment login --env ${env.name}`
+    throw new Error(
+      `${need} needs ${
+        /^[aeiou]/.test(required) ? 'an' : 'a'
+      } "${required}" session.${asWho}\n\n  Log in as an account that has it:\n    ${how}\n`
+    )
   }
 }
 
 // ── reads ───────────────────────────────────────────────────────────────────
-const USER_COLUMNS = `users_pk AS id, email, first_name, last_name,
-  fk_user_roles_at_dooer_pk AS role, id_number AS personnummer, email_verified,
-  inactivated_at, internal, language, inserted_at, (password_hash IS NOT NULL) AS has_password`
+const USER_FIELDS = `id email firstName lastName userType sePersonnummer isEmailVerified
+  isInactivated inactivatedAt createdAt language internal`
+
+async function searchUsers(env, { query, role, limit }) {
+  const filter = role ? `userType eq "${role}"` : null
+  const data = await withLevel(env, 'listing users', () =>
+    remote.gql(
+      env,
+      `query ($q: String, $filter: String, $first: Int) {
+      users(q: $q, filter: $filter, first: $first) { edges { node { ${USER_FIELDS} } } }
+    }`,
+      { q: query || null, filter, first: limit }
+    )
+  )
+  return data.users.edges.map((e) => e.node)
+}
 
-// A user is addressed by uuid or by email — nobody remembers uuids.
-async function findUser(db, ref) {
-  const byId = UUID_RE.test(ref)
-  const { rows } = await db.query(
-    `SELECT ${USER_COLUMNS} FROM ${T_USERS} WHERE ${byId ? 'users_pk = $1' : 'lower(email) = lower($1)'}
-     ORDER BY inserted_at`,
-    [ref]
+// Addressable by uuid or email — nobody remembers uuids.
+async function findUser(env, ref) {
+  if (UUID_RE.test(ref)) {
+    const data = await withLevel(env, 'reading a user', () =>
+      remote.gql(env, `query ($id: ID!) { user(id: $id) { ${USER_FIELDS} } }`, { id: ref })
+    )
+    if (!data.user) throw new Error(`no user with id ${ref}`)
+    return data.user
+  }
+  const data = await withLevel(env, 'looking a user up by email', () =>
+    remote.gql(
+      env,
+      `query ($filter: String) { users(filter: $filter, first: 10) { edges { node { ${USER_FIELDS} } } } }`,
+      { filter: `email eq "${ref.replace(/"/g, '\\"')}"` }
+    )
   )
+  const rows = data.users.edges.map((e) => e.node)
   if (!rows.length) throw new Error(`no user matching "${ref}"`)
   if (rows.length > 1) {
-    // email is unique per ROLE (users_email_fk_user_roles_at_dooer_pk_key), so one address can legitimately
-    // exist as both a `customer` and an `hi`. Make the caller say which.
+    // One address can exist once per user type, so an ambiguous email must be resolved by the caller.
     throw new Error(
-      `"${ref}" matches ${rows.length} users (one per role: ${rows.map((r) => r.role).join(', ')}) — ` +
+      `"${ref}" matches ${rows.length} users (${rows.map((r) => r.userType).join(', ')}) — ` +
         `address it by id: ${rows.map((r) => r.id).join(', ')}`
     )
   }
   return rows[0]
 }
 
-async function searchUsers(db, { query, role, limit }) {
-  const where = []
-  const params = []
-  if (query) {
-    params.push(`%${query}%`)
-    where.push(`(email ILIKE $${params.length} OR first_name ILIKE $${params.length}
-                 OR last_name ILIKE $${params.length} OR id_number ILIKE $${params.length}
-                 OR users_pk::text ILIKE $${params.length})`)
-  }
-  if (role) {
-    params.push(role)
-    where.push(`fk_user_roles_at_dooer_pk = $${params.length}`)
-  }
-  params.push(limit)
-  const { rows } = await db.query(
-    `SELECT ${USER_COLUMNS} FROM ${T_USERS}
-     ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
-     ORDER BY inserted_at DESC LIMIT $${params.length}`,
-    params
+async function listPartners(env) {
+  const data = await withLevel(env, 'listing every partner', () =>
+    remote.gql(env, `query { partners(first: 200) { edges { node { id name domain status } } } }`)
   )
-  return rows
+  return data.partners.edges.map((e) => e.node)
 }
 
-async function listPartners(db) {
-  const { rows } = await db.query(
-    `SELECT p.id, p.name, p.domain, p.status, p."isDefaultPartner",
-            count(pu.id)::int AS users
-     FROM ${T_PARTNER} p LEFT JOIN ${T_PARTNER_USER} pu ON pu."partnerId" = p.id
-     GROUP BY p.id ORDER BY p.name`
+// The partners one user belongs to, with the level from each partner's membership row.
+async function partnersForUser(env, userId) {
+  const data = await withLevel(env, 'reading a user’s partners', () =>
+    remote.gql(env, `query ($id: ID!) { user(id: $id) { partners { id name domain } } }`, { id: userId })
+  )
+  const partners = (data.user && data.user.partners) || []
+  return Promise.all(
+    partners.map(async (p) => {
+      try {
+        const d = await remote.gql(
+          env,
+          `query ($pid: ID!, $uid: ID!) { partner(id: $pid) { user(userId: $uid) { role status defaultRepresentative } } }`,
+          { pid: p.id, uid: userId }
+        )
+        const pu = d.partner && d.partner.user
+        return {
+          ...p,
+          level: pu && pu.role,
+          status: pu && pu.status,
+          defaultRepresentative: pu && pu.defaultRepresentative,
+        }
+      } catch (_) {
+        // Membership detail needs partner level for THAT partner; the membership itself is still true.
+        return { ...p, level: null, status: null, defaultRepresentative: null }
+      }
+    })
   )
-  return rows
 }
 
-// Same shape as GET /v1/partners/views/by-user/:userId, plus the membership level.
-async function partnersForUser(db, userId) {
-  const { rows } = await db.query(
-    `SELECT p.id, p.name, p.domain, pu.role AS level, pu.status,
-            pu."inProduction", pu."defaultRepresentative", pu."lastLoginAt"
-     FROM ${T_PARTNER_USER} pu JOIN ${T_PARTNER} p ON p.id = pu."partnerId"
-     WHERE pu."userId" = $1 ORDER BY p.name`,
-    [userId]
+async function findPartner(env, ref) {
+  if (UUID_RE.test(ref)) {
+    const data = await withLevel(env, 'reading a partner', () =>
+      remote.gql(env, `query ($id: ID!) { partner(id: $id) { id name domain status } }`, { id: ref })
+    )
+    if (!data.partner) throw new Error(`no partner with id ${ref}`)
+    return data.partner
+  }
+  const all = await listPartners(env)
+  const hit = all.filter(
+    (p) => p.name.toLowerCase() === ref.toLowerCase() || p.domain.toLowerCase() === ref.toLowerCase()
   )
-  return rows
+  if (!hit.length) throw new Error(`no partner matching "${ref}" (see: dooer-test-env partner list --env ${env.name})`)
+  if (hit.length > 1) throw new Error(`"${ref}" matches ${hit.length} partners — address it by id`)
+  return hit[0]
 }
 
-async function findPartner(db, ref) {
-  const byId = UUID_RE.test(ref)
-  const { rows } = await db.query(
-    `SELECT id, name, domain, status FROM ${T_PARTNER}
-     WHERE ${byId ? 'id = $1' : '(lower(name) = lower($1) OR lower(domain) = lower($1))'} ORDER BY name`,
-    [ref]
+async function partnerUsers(env, partnerId) {
+  const data = await withLevel(env, 'listing a partner’s users', () =>
+    remote.gql(
+      env,
+      `query ($id: ID!) {
+      partner(id: $id) { users(first: 500) { edges { node {
+        userId role status defaultRepresentative user { email firstName lastName }
+      } } } }
+    }`,
+      { id: partnerId }
+    )
   )
-  if (!rows.length) throw new Error(`no partner matching "${ref}" (see: dooer-test-env partner list)`)
-  if (rows.length > 1) {
-    throw new Error(`"${ref}" matches ${rows.length} partners — address it by id: ${rows.map((r) => r.id).join(', ')}`)
-  }
-  return rows[0]
+  return data.partner.users.edges.map((e) => e.node)
 }
 
 // ── writes ──────────────────────────────────────────────────────────────────
-async function createUser(db, { email, password, role, personnummer, firstName, lastName, execute }) {
-  // Enforced by users_email_fk_user_roles_at_dooer_pk_key — check first so the failure is a sentence
-  // rather than a constraint-violation dump.
-  const {
-    rows: clash,
-  } = await db.query(
-    `SELECT users_pk FROM ${T_USERS} WHERE lower(email) = lower($1) AND fk_user_roles_at_dooer_pk = $2`,
-    [email, role]
-  )
-  if (clash.length) throw new Error(`a "${role}" user with email ${email} already exists (${clash[0].users_pk})`)
-
-  const hash = hashPassword(password)
-  const apiUuid = crypto.randomUUID()
-  // email_verified: these are test accounts — an unverified address puts a verification wall in front of
-  // every flow you actually wanted to exercise.
-  const values = [role, firstName, lastName, email, personnummer || null, hash, apiUuid]
-  // No id yet on a dry-run — the caller must not go on to use it as one (a placeholder string blew up the
-  // partner lookup's uuid parameter).
-  if (!execute) return { id: null, apiUuid }
-  const { rows } = await db.query(
-    `INSERT INTO ${T_USERS}
-       (fk_user_roles_at_dooer_pk, first_name, last_name, email, id_number, password_hash, api_uuid,
-        email_verified)
-     VALUES ($1, $2, $3, $4, $5, $6, $7, true)
-     RETURNING users_pk AS id, api_uuid`,
-    values
+async function createUser(env, { email, password, role, personnummer, firstName, lastName }) {
+  const input = { email, password, userType: role, firstName, lastName }
+  if (personnummer) input.sePersonnummer = personnummer
+  const data = await withLevel(env, 'creating a user', () =>
+    remote.gql(
+      env,
+      `mutation ($input: UserInput!) {
+      users { create(input: $input) { id email userType } }
+    }`,
+      { input }
+    )
   )
-  return { id: rows[0].id, apiUuid: rows[0].api_uuid }
+  return data.users.create
 }
 
-async function assignPartner(db, { user, partner, level, execute }) {
-  // The guard from setPartnerUser: partner membership is for accounting professionals only. Without it
-  // the CLI would happily write a row that HQ then trips over.
-  if (user.role !== 'hi') {
-    throw new Error(
-      `only "hi" users can belong to a partner (${user.email} is "${user.role}") — ` +
-        `this is the same invalid-user-type check the service-accounts API applies`
+async function assignPartner(env, { userId, partnerId, level }) {
+  const data = await withLevel(env, 'changing partner membership', () =>
+    remote.gql(
+      env,
+      `mutation ($pid: ID!, $uid: ID!, $input: PartnerUserInput!) {
+      partner(id: $pid) { users { set(userId: $uid, input: $input) { userId role status } } }
+    }`,
+      { pid: partnerId, uid: userId, input: { role: level, status: 'enabled' } }
     )
-  }
-  const {
-    rows: existing,
-  } = await db.query(`SELECT role AS level FROM ${T_PARTNER_USER} WHERE "partnerId" = $1 AND "userId" = $2`, [
-    partner.id,
-    user.id,
-  ])
-  if (!execute) return { previous: existing[0] ? existing[0].level : null }
-  const { rows } = await db.query(
-    `INSERT INTO ${T_PARTNER_USER} ("partnerId", "userId", role, status)
-     VALUES ($1, $2, $3, 'enabled')
-     ON CONFLICT ("partnerId", "userId")
-       DO UPDATE SET role = EXCLUDED.role, status = EXCLUDED.status, "updatedAt" = now()
-     RETURNING role AS level`,
-    [partner.id, user.id, level]
   )
-  return { previous: existing[0] ? existing[0].level : null, level: rows[0].level }
+  return data.partner.users.set
 }
 
-async function unassignPartner(db, { user, partner, execute }) {
-  const {
-    rows: existing,
-  } = await db.query(`SELECT role AS level FROM ${T_PARTNER_USER} WHERE "partnerId" = $1 AND "userId" = $2`, [
-    partner.id,
-    user.id,
-  ])
-  if (!existing.length) throw new Error(`${user.email} is not a member of ${partner.name}`)
-  if (execute) {
-    await db.query(`DELETE FROM ${T_PARTNER_USER} WHERE "partnerId" = $1 AND "userId" = $2`, [partner.id, user.id])
-  }
-  return { level: existing[0].level }
-}
-
-// Every command opens one connection and closes it, so the CLI never leaves a socket to the cluster open.
-async function withDb(namespace, fn) {
-  const db = await connect(namespace)
-  try {
-    return await fn(db)
-  } finally {
-    try {
-      await db.client.end()
-    } catch (_) {
-      /* already gone */
-    }
-  }
+async function unassignPartner(env, { userId, partnerId }) {
+  await withLevel(env, 'removing partner membership', () =>
+    remote.gql(env, `mutation ($pid: ID!, $uid: ID!) { partner(id: $pid) { user(userId: $uid) { delete } } }`, {
+      pid: partnerId,
+      uid: userId,
+    })
+  )
 }
 
 module.exports = {
   USER_ROLES,
   PARTNER_LEVELS,
-  targetOf,
-  guardWrite,
   generatePassword,
-  hashPassword,
   normalizePersonnummer,
   namesFromEmail,
-  findUser,
   searchUsers,
+  findUser,
   listPartners,
   partnersForUser,
   findPartner,
+  partnerUsers,
   createUser,
   assignPartner,
   unassignPartner,
-  withDb,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooer/dooer-test-env",
-  "version": "1.14.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",
@@ -27,12 +27,12 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.600.0",
     "@dooer/package-info": "^1.6.7",
-    "bcryptjs": "^3.0.3",
     "chalk": "^4.1.2",
     "js-yaml": "^3.14.1",
     "pg": "^8.23.0",
     "pg-copy-streams": "^6.0.0",
     "pg-cursor": "^2.11.0",
+    "qrcode-terminal": "^0.12.0",
     "yargs": "^17.7.2"
   },
   "devDependencies": {

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,8 @@ 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)
-user search | get | create | partners             find/inspect/create users (local env unless --target-namespace)
+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)
 bankid pull | status | clear                      BankID cert (staging → keychain), used by service-accounts
@@ -125,17 +129,22 @@ npx @dooer/dooer-test-env@latest user create --email anna@dooer.com --execute
 
 # …a customer instead, with your own password and a personnummer
 npx @dooer/dooer-test-env@latest user create --email kim@example.com \
-  --role customer --password 'hunter2hunter2' --personnummer 19900101-1234 --execute
+  --role customer --password 'hunter2hunter2' --personnummer 19900101-1239 --execute
 
 # …or an `hi` user placed straight into a partner
 npx @dooer/dooer-test-env@latest user create --email anna@dooer.com \
   --partner "Dooer Devteam" --level admin --execute
 ```
 
-The password is stored the way signup stores it (bcrypt, cost 10), so it works on the ordinary
-email+password login — no BankID needed. It is shown **once**; there is no way to read it back. `--role`
-defaults to `hi` (other choices: `customer`, `admin`), names default to something derived from the address,
-and the account is created with its email pre-verified so no verification wall gets in the way.
+This goes through `users.create` — the same mutation back-office's `/users/new` calls — so the service
+hashes the password itself and applies its own input validation. The password works on the ordinary
+email+password login, no BankID needed, and is shown **once**; there is no way to read it back. `--role`
+defaults to `hi` (other choices: `customer`, `admin`) and names default to something derived from the
+address.
+
+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). Creating a user needs an **admin** session in a
+remote environment — see below.
 
 Look users up by email **or** id, and see where they belong:
 
@@ -147,7 +156,7 @@ npx @dooer/dooer-test-env@latest user get anna@dooer.com   # details + partner m
 ### Partners and who belongs to them
 
 ```bash
-npx @dooer/dooer-test-env@latest partner list                        # every partner + user counts
+npx @dooer/dooer-test-env@latest partner list                        # every partner in the environment
 npx @dooer/dooer-test-env@latest partner users "Dooer Devteam"       # its users and their level
 
 # add / promote / remove (a partner is addressable by id, name or domain)
@@ -161,15 +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
 
-These commands default to the local env. Point them at a cluster with `--target-namespace`:
+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 — what HQ does, so you get your professional (hi) account
+npx @dooer/dooer-test-env@latest remote-environment login --env staging
+
+# 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
+```
+
+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 --target-namespace dooer-staging
-npx @dooer/dooer-test-env@latest partner list --target-namespace dooer-production
+npx @dooer/dooer-test-env@latest user search someone@dooer.com --env staging
+npx @dooer/dooer-test-env@latest partner list --env production
+```
+
+**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.
+
+### Use the session token in your own scripts
+
+`remote-environment token` prints the token and nothing else — no colour, no label — so it drops straight
+into a variable or a pipe:
+
+```bash
+TOKEN=$(npx @dooer/dooer-test-env@latest 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 } }"}'
 ```
 
-Writes there are still dry-run until `--execute`, and `dooer-production` additionally demands
-`--confirm-production`.
+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