🏗️ PUT-1704 + PUT-1707: TeamService — workspace lifecycle, disable and re-enable

[jfcastro92]

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

Covers PUT-1704 (create a workspace, admit the workspace owner) and PUT-1707 (disable and re-enable) together — both are TeamService methods and neither is large enough to review alone.

createWorkspace(ownerUserId, { name, handle? })
checkOwnerInvariant(teamUid)

requireMembership(teamUid, actorUserId)     -> 404 to a stranger
requireOwner(teamUid, actorUserId)         -> 403 to a non-master member
requireOrgAccount(teamUid, targetUserId)    -> 404 for the workspace owner

disableMember(teamUid, actorUserId, targetUserId)
enableMember(teamUid, actorUserId, targetUserId)

⚠ A spec bug worth reading before the code

PUT-1707 said to set user.suspended_at / suspended_reason (0061, 0063). Those are real columns — but neither of them enforces anything:

// core/http/middleware/userProtected.ts:175
if (user.suspended)
    throw new HttpError(403, 'Account is suspended', { … });

The enforced column is the older boolean suspended from 0001. suspended_at and suspended_reason are its siblings; 0061's own comment calls it "the timestamp sibling of the existing boolean suspended flag".

Implemented literally, disable would have written a perfect record of an offboarding that never happened — and since this design has no remove-from-workspace, no file transfer and no retention clock, disable is the entire offboarding control. All three columns are now written together, and the test is named for it: sets the column the request gate actually reads. Ticket and design doc corrected.

The invariant no dialect can express

createWorkspace admits the creator with org_owned = 0. That single value is what makes the workspace owner pay for itself and stay an invalid target of every member route.

checkOwnerInvariant asserts what the schema cannot: the owner is a member with org_owned = 0, and is the only such member. There's a test that deliberately breaks it by admitting a second org_owned = 0 account, because nothing in any dialect refuses that — which is the reason the check exists at all.

Authority

Three checks, and between them the whole authorization model:

Caller	Result
Not a member	404 team_not_found — so the endpoint is not an existence oracle
Member, not the owner	403 not_the_workspace_owner
The master, targeting itself	404 not_an_org_account — org_owned is tested explicitly, never inferred from NULL

Adds those three values to the HttpError legacy-code union, which is a closed type. PUT-1708's routes need the same three.

What is deliberately not here

Stated rather than buried, since PUT-1707 lists them:

Deferred	To
Billing events on disable / re-enable	phase 3, PUT-1712
invalidateActorSubscription	phase 3
Audit rows for both operations	PUT-1708, which owns audit writes
outer.gui.* push + member notification	needs a new event type and socket fan-out — design work belonging with the controller/GUI phase

---

Verification

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

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

$ npm run test:backend
 Test Files  252 passed | 24 skipped (276)
      Tests  6743 passed | 26 skipped (6769)      # +13, no regressions

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

The disable tests assert the observable consequences rather than the write: sessions are gone, fsentries are untouched, re-enable clears all three columns, the workspace owner cannot be disabled even by itself, a non-master's disable order is refused, and a member of another workspace cannot be reached.

A detail that cost six red tests

HttpError exposes statusCode, not status. My first assertions used toMatchObject({ status: 404 }), which fails against every HttpError regardless of what it actually contains — so all six rejection tests failed while the seven behavioural ones passed. Worth knowing before writing the controller tests in PUT-1708, where nearly every assertion is a rejection.

---

Closes PUT-1704 and PUT-1707.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	93.93% ⬇️ -0.04%	27450 / 29222
🔵	Statements	92.04% ⬇️ -0.03%	29753 / 32326
🔵	Functions	90.4% ⬆️ +0.01%	4938 / 5462
🔵	Branches	80.89% ⬇️ -0.02%	19789 / 24462

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/backend/core/http/HttpError.ts	100% 🟰 ±0%	88.88% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%
src/backend/services/index.ts	100% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%	100% 🟰 ±0%
src/backend/services/team/TeamService.ts	68.11%	54.76%	84.61%	71.87%	81-83, 86-88, 97-130, 159-162, 170, 176

Generated in workflow #1425 for commit aad4994 by the Vitest Coverage Report Action

[Salazareo]

I'm a bit unsure about whether or not we should use suspended column for this. We've primarily used it for abuse prevention, so might cause some unwanted effects in gui/ prod metrics.

that said, the reason field might be enough to have that not be a problem, but well need to start checking and exposing that reason (only if its disabled by workspace).

i leave it to you to decide, but just make sure that this suspended reason is handled properly everywhre

[jfcastro92]

Local validation

Engine: mysql 8 · teams_enabled: true

Disable suspends the account and kills the live session

before   suspended=NULL   /whoami -> 200
POST /teams/<uid>/members/acmeseat1/disable -> 200 {"success":true}
after    suspended=1      /whoami -> 401

Re-enable clears suspension, and deliberately does not resurrect the old
session

POST /teams/<uid>/members/acmeseat1/enable -> 200 {"success":true}
after    suspended=0      /whoami (old token) -> 401

The old token staying dead is the right behaviour — re-enabling an account should
not revive sessions that were revoked when it was disabled. A fresh sign-in works:

login as acmeseat1 -> 200, new session token
/whoami with it    -> 200

Both transitions are audited, with actor attribution:

{"action":"enable",  "username":"acmeseat1","actor_username":"tmowner","created_at":"...23:29:40.000Z"}
{"action":"disable", "username":"acmeseat1","actor_username":"tmowner","created_at":"...23:29:39.000Z"}

Lifecycle behaves as described, and the disable → re-enable → fresh-login round
trip works end to end against a real database and a real session store.