🏗️ PUT-1705: TeamService — provision an org account

[jfcastro92]

Seventh in the stack: #3704 → #3705 → #3708 → #3709 → #3710 → #3712 → this. Review bottom-up.

PUT-1705 on its own. This is the operation the feature exists for, it creates real user accounts and sends mail, so it doesn't share a review with anything.

provisionAccount(teamUid, actorUserId, { username, email })
    -> { userId, username, activationLink }
suggestUsernames(username, count?)
resendActivation(teamUid, actorUserId, targetUserId)

Activation reuses password recovery

No new token machinery, no team_activation table, no unauthenticated endpoint on the team surface. Provisioning sets the same pass_recovery_token that /send-pass-recovery-email uses, signs the same one-hour otp JWT with purpose: 'pass-recovery', and hands back the same /action/set-new-password link.

That inherits, for free: a one-shot token cleared on use, expiry carried in a signed JWT rather than a DB column, atomic single-use consumption, purpose scoping so the link can't be replayed for another operation, and refusal for suspended accounts.

Activation state needs no column either. An unactivated account is one with no password — the predicate migration 0066 already uses. resendActivation refuses an account that has one, because re-sending then would be a password reset wearing the wrong name.

Usernames come from the global pool

Usernames are globally unique and case-insensitive (idx_user_username_nocase, 0055), so a workspace provisions from the same namespace as every other Puter user. Two companies cannot both have a juan.

What provisioning adds is a check and a suggestion — never a silent modification. A suffixed juan-castro-2 would appear in every share dialog that person ever sees, and they never agreed to it. So a taken name is refused with username_already_in_use plus alternatives that have been verified free, and the administrator chooses.

⚠ The check runs before any write. A taken name failing part-way through account setup would leave an orphaned user row and a half-provisioned account. There's a test asserting the workspace's member count is unchanged after a rejected provision.

Two smaller decisions

requires_email_confirmation is set on the new account. The address came from the administrator, not its holder, so it is unverified by definition — and §5.5 later depends on that address being the member's, which makes confirming it load-bearing rather than tidy.

The team_account_activation template states what the workspace can and cannot do:

• This account belongs to {{team_name}}. They pay for it and can close it.
• {{team_name}} cannot see your files, apps or data.
• {{team_name}} can reset your password. You will be emailed each time that happens, and every reset is recorded where you can see it.

That last line is required, not padding. Stating only that admins cannot see the contents would describe a guarantee the system does not make.

The equivalent disclosure on the set-password screen is phase 6, since that's GUI.

---

Verification

$ npx vitest run --config src/backend/vitest.config.ts src/backend/services/team/
 Test Files  1 passed (1)
      Tests  21 passed (21)

$ PUTER_TEST_DB_ENGINE=postgres npx vitest run --config src/backend/vitest.config.ts src/backend/services/team/
 Test Files  1 passed (1)
      Tests  21 passed (21)

$ npm run test:backend
 Test Files  252 passed | 24 skipped (276)
      Tests  6751 passed | 26 skipped (6777)      # +8, no regressions

$ npm run typecheck
Type check passed — no new errors (33 known, baselined).

Eight tests added: the account is created password-less and owned by the workspace, it gets its filesystem tree (trash_uuid set, which is also generateDefaultFsentries' own idempotency guard), the activation link is returned and a recovery token stored, a taken username writes nothing, suggestions are verified free and never equal the taken name, a non-master is refused, re-issuing rotates the token, and an activated account cannot be re-sent.

Not here

Deferred	To
user.free_storage stamped from a team policy	deleted, not deferred — a seat is an ordinary account on the common tier, so its ceiling is config.storage_capacity like any other. See TEAMS-BILLING-SPLIT.md
The billing event that starts the per-account charge	phase 3, PUT-1712
Audit row for provision	PUT-1708
Disclosure on the set-password screen	phase 6

---

Closes PUT-1705.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	93.93% ⬇️ -0.04%	27502 / 29278
🔵	Statements	92.03% ⬇️ -0.05%	29808 / 32386
🔵	Functions	90.42% ⬆️ +0.03%	4946 / 5470
🔵	Branches	80.9% ⬇️ -0.01%	19819 / 24498

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/backend/clients/email/templates.ts	100% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%
src/backend/controllers/auth/AuthController.ts	90.78% ⬆️ +0.01%	79.25% ⬆️ +0.02%	77.77% 🟰 ±0%	91.73% ⬆️ +0.01%	6, 24-26, 32, 33, 34, 38-39, 44, 45, 47, 474-476, 490-492, 620-621, 695-697, 714-716, 858, 920-924, 942, 984-989, 998, 1009, 1024-1029, 1035, 1079-1080, 1083-1088, 1231, 1262-1263, 1282-1286, 1324-1326, 1328-1330, 1378, 1406-1417, 1492-1494, 1507, 1567-1569, 1603, 1616-1618, 1644-1646, 1677, 1681-1683, 1781, 1867, 1926, 1971, 2030, 2043-2046, 2088-2090, 2108-2111, 2165-2167, 2179-2181, 2197-2199, 2213-2216, 2222, 2241, 2252, 2373-2377, 2406, 2437-2439, 2451-2457, 2517-2522, 2596-2598, 2661, 2699, 2740-2742, 2808, 2838, 2917-2919, 2921-2923, 2927-2930, 2943-2946, 3011-3016, 3019-3021, 3048, 3067, 3085, 3103, 3116, 3139, 3151, 3168, 3178, 3189, 3243, 3376-3380, 3402-3404, 3418, 3421-3425, 3500
src/backend/services/team/TeamService.ts	77.77%	65.33%	90%	81.19%	107-109, 112-114, 123-156, 185-188, 196, 202, 239, 299-302, 334-336, 356, 371

Generated in workflow #1446 for commit 673f7fe by the Vitest Coverage Report Action

[Salazareo]

one comment there

[jfcastro92]

Local validation

Engine: mysql 8 · teams_enabled: true · max_seats_per_workspace: 3

Provisioning three seats, then hitting the cap

seat1 [HTTP 200] {"username": "acmeseat1", "temporary_password": "<redacted len=16>"}
seat2 [HTTP 200] {"username": "acmeseat2", "temporary_password": "<redacted len=16>"}
seat3 [HTTP 200] {"username": "acmeseat3", "temporary_password": "<redacted len=16>"}
seat4 [HTTP 409] {"error": "This workspace is limited to 3 seats",
                  "code": "seat_limit_reached", "limit": 3}

The rows that result — seats are org_owned=1, the owner is not:

username     email_confirmed  req_email  req_pw  suspended  org_owned
tmowner            1              0        0       NULL         0
acmeseat1          0              1        1       NULL         1
acmeseat2          0              1        1       NULL         1
acmeseat3          0              1        1       NULL         1

Provisioning mail actually delivered (mailhog, real SMTP — not a spy), carrying the
workspace's current name:

to=['acmeseat3@example.test'] subj='Your Acme Renamed account on Puter'
to=['acmeseat2@example.test'] subj='Your Acme Renamed account on Puter'
to=['acmeseat1@example.test'] subj='Your Acme Renamed account on Puter'

Body confirms no credential is included, as intended — the password goes out of band.

Credential reissue returns a fresh one-time password

POST /teams/:uid/members/acmeseat1/activation -> 200, temporary_password len=16
login as acmeseat1 with it                    -> 200, session token issued

Provisioning, the seat cap, org_owned, and the mail path all behave as described.

---

⚠ One follow-up, tracked in PUT-1745 rather than here: reissueCredential's
requires_password_change guard does not currently become effective, so the
"already activated" 409 is not reachable and reissue is not rate-bounded by
activation state. Detail and suggested Done-when changes are on that ticket. It
is not reachable in any deployment — teams_enabled is false by default.