Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.

In `@apps/backend/src/app/api/latest/team-invitations/`[id]/accept/route.tsx:
- Around line 72-76: The thrown StackAssertionError when matchingChannel is
missing is a user-facing error; replace it so the route throws a KnownError (or
an existing specific known error) instead of StackAssertionError. Update the
block that currently throws StackAssertionError to throw
KnownErrors.EmailMismatch (or new KnownError(KnownErrors.EmailMismatch) if the
API expects an instance) so the client receives the proper HTTP status and
message; ensure you import/use the KnownErrors/KnownError symbols consistently
with other routes.
- Around line 40-131: The verification code check and the final usedAt update
have a TOCTOU race: move the verificationCode update into the same transaction
that adds the team member (i.e., inside retryTransaction) so the read-and-mark
happen atomically, or at minimum change the standalone
globalPrismaClient.verificationCode.update call to include usedAt: null in its
where clause and handle the case where no rows are updated (throw
KnownErrors.VerificationCodeNotFound or similar); update the code that performs
membership creation (teamMembershipsCrudHandlers.adminCreate) and the
verificationCode update together inside the retryTransaction block that
currently contains the membership logic, using the same prisma transaction (tx)
and the same params.id / auth.tenancy identifiers.
- Around line 57-58: The code is unsafely casting database JSON with "const
invitationData = code.data as { team_id: string }" and "const invitationMethod =
code.method as { email: string }"; replace these blind casts with runtime
validation: define a zod (or yup) schema for the expected shapes (e.g.,
team_id:string and email:string) and run schema.parse()/validateSync() on
code.data and code.method inside the accept route handler (or, if you prefer not
to add a schema lib, explicitly check the presence and types of team_id and
email and throw a descriptive error if missing) so downstream logic using
invitationData and invitationMethod cannot proceed with undefined fields. Ensure
you reference the validated values (invitationData, invitationMethod) everywhere
they are used and remove the `as` casts.

In `@apps/backend/src/app/api/latest/team-invitations/crud.tsx`:
- Around line 72-82: The bare catch blocks around the
teamsCrudHandlers.adminRead loop (the loop over teamIds that calls
teamsCrudHandlers.adminRead and populates teamsMap with teamsMap.set) must not
swallow all errors; change the catch to capture the error (catch (err)) and only
handle the expected "team not found" case (e.g., check err.code/err.status or
err instanceof NotFoundError or use an isNotFound(err) helper) by skipping that
ID, otherwise rethrow or log and surface the error; apply the same change to the
second occurrence that also calls teamsCrudHandlers.adminRead so unexpected
network/permission/timeout errors are not silently ignored.
- Around line 29-34: The guard is throwing when auth.user is null for
server/admin cases; only enforce fetching currentUserId for client auth. Change
the block that handles query.user_id so it first checks auth.type === 'client'
and only then reads auth.user?.id (assign to currentUserId) and compares it to
query.user_id, throwing KnownErrors.CannotGetOwnUserWithoutUser() or the
mismatch error for client requests; for non-client (server/admin) allow the
provided query.user_id without attempting to access auth.user.
- Around line 66-82: The loop that builds teamsMap by calling
teamsCrudHandlers.adminRead for each teamId (teamIds, teamsMap,
teamsCrudHandlers.adminRead) produces an N+1 serial query pattern; replace it
with a single batch fetch that returns all teams for the set of teamIds (e.g.,
implement/use a teamsCrudHandlers.adminReadMany or teamsCrudHandlers.adminList
with a filter by team_ids) and then populate teamsMap from that single response,
ensuring you handle missing/deleted teams by skipping or omitting them.
- Around line 22-27: Replace the internal StackAssertionError uses in the
validation for team_id/user_id with an HTTP-friendly KnownErrors instance so
clients get a 400: in the branch that checks "if (query.team_id != null &&
query.user_id != null)" throw a KnownErrors.BadRequest (or
KnownErrors.InvalidRequest) with a clear message like "Cannot specify both
team_id and user_id", and in the branch that checks "if (query.team_id == null
&& query.user_id == null)" throw a KnownErrors.BadRequest (or
KnownErrors.InvalidRequest) with "Must specify either team_id or user_id";
reference the existing StackAssertionError, query.team_id, query.user_id, and
KnownErrors symbols when making the replacement so the validation returns an
HTTP 400 instead of an internal assertion.

In `@apps/e2e/tests/backend/endpoints/api/v1/team-invitations.test.ts`:
- Around line 182-188: The test "it(\"can't list invitations without team_id or
user_id\"" incorrectly expects a 500; change the assertion to expect a 4xx
client error (e.g., 400) or the specific schema error code returned by your
validation layer and verify the error payload shape instead of a 500. Update the
expect call on listInvitationsResponse.status to assert the appropriate 4xx
status and optionally assert that the response body indicates a SchemaError; if
the API currently returns 500, update the validation/handler for GET
`/api/v1/team-invitations` to validate presence of team_id or user_id and return
the correct 4xx status so the test passes.

In `@packages/stack-shared/src/interface/client-interface.ts`:
- Around line 1190-1199: The acceptTeamInvitationById method currently builds
the endpoint with template interpolation which bypasses URL encoding; update
acceptTeamInvitationById to construct the path using the existing urlString
helper (same pattern as other methods) when calling sendClientRequest so the
invitationId is encoded consistently; modify the call in
acceptTeamInvitationById to pass
urlString(`/team-invitations/${invitationId}/accept`) to sendClientRequest
instead of the raw template string.

In `@packages/stack-shared/src/interface/server-interface.ts`:
- Around line 444-453: The method acceptServerTeamInvitationById currently
ignores the userId parameter; update the client and server to pass user context
by adding user_id as a query parameter when calling sendServerRequest (i.e.,
include userId in the urlString for /team-invitations/${invitationId}/accept) so
the backend receives auth.user, and update the backend endpoint handling for
POST /team-invitations/{id}/accept to accept and validate a user_id query
parameter (add it to the endpoint's querySchema and use it to set auth.user when
running server-side logic).

In `@packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts`:
- Around line 819-833: The accept handler in
_serverReceivedTeamInvitationFromCrud currently refreshes
_serverUserTeamInvitationsCache and _serverTeamsCache but not the team
invitation list, leaving admins with stale data; update the accept async
function in _serverReceivedTeamInvitationFromCrud to also call and await
app._serverTeamInvitationsCache.refresh([...]) (use the relevant identifier,
e.g. await app._serverTeamInvitationsCache.refresh([crud.team_id]) so the team’s
invitation list is refreshed after accept).

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/stack-shared/src/interface/server-interface.ts`:
- Around line 434-442: The method listServerUserTeamInvitations casts the
response to TeamInvitationCrud['Client']['List'] and returns
TeamInvitationCrud['Client']['Read'][] which drops server-only fields; change
the response cast and return type to TeamInvitationCrud['Server']['List'] /
TeamInvitationCrud['Server']['Read'][] (matching listServerTeamInvitations) and
keep using sendServerRequest as-is so the server-level fields are preserved;
update the type assertion on the response.json() and the method signature
accordingly.

---

Duplicate comments:
In `@packages/stack-shared/src/interface/client-interface.ts`:
- Around line 1212-1221: The acceptTeamInvitationById method builds the request
path using a raw template literal which doesn't URL-encode the invitationId;
update the path construction to use the urlString template tag (or
encodeURIComponent) instead of ``/team-invitations/${invitationId}/accept`` so
the segment is encoded consistently with the codebase and then call
sendClientRequest with that encoded path; change the path in
acceptTeamInvitationById to use
urlString`/team-invitations/${invitationId}/accept` (keeping the same method,
body, and session parameters).

In `@packages/stack-shared/src/interface/server-interface.ts`:
- Around line 444-453: The acceptServerTeamInvitationById function is ignoring
the userId parameter so the POST to /team-invitations/{invitationId}/accept
carries no user context; update acceptServerTeamInvitationById to append user_id
as a query parameter (e.g.,
/team-invitations/${invitationId}/accept?user_id=${userId}) when calling
sendServerRequest so the backend receives user_id, and then update the backend
route handler for /team-invitations/[id]/accept to add a querySchema that
accepts user_id and uses it to resolve auth.user when no access token is present
(ensure code paths that currently read auth.user fall back to the supplied
user_id).

In `@packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts`:
- Around line 827-831: The accept handler currently calls
app._interface.acceptServerTeamInvitationById and refreshes
app._serverUserTeamInvitationsCache and app._serverTeamsCache but omits
refreshing the team-scoped caches; update the accept function to also refresh
app._serverTeamInvitationsCache and app._serverTeamMemberProfilesCache after
acceptance, using the appropriate cache keys (e.g., the team id and/or member id
from crud or the returned result) so that
team.listInvitations()/team.useInvitations() and
team.listUsers()/team.useUsers() see the new state immediately.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/backend/src/app/api/latest/team-invitations/`[id]/accept/route.tsx:
- Around line 90-129: The current flow calls
teamMembershipsCrudHandlers.adminCreate outside the retryTransaction and updates
verificationCode.usedAt after the transaction, breaking atomicity; move the
verificationCode.update into the retryTransaction body and ensure membership
creation uses the transaction (either by passing tx into
teamMembershipsCrudHandlers.adminCreate if it supports a prisma instance, or
replace the call with tx.teamMember.create within the retryTransaction) so both
the membership creation and verificationCode.update (usedAt) occur under the
same tx in retryTransaction to avoid partial commits and retry duplication
issues.
- Around line 69-70: The current unchecked casts of code.data and code.method to
{ team_id: string } and { email: string } are unsafe; instead parse and validate
these Json fields in the accept route so you explicitly throw on missing/invalid
values. Replace the direct casts/uses of invitationData.team_id and
invitationMethod.email by extracting teamId and recipientEmail from
code.data/code.method with runtime checks (e.g., if not a string then throw with
a clear message) and then use teamId and recipientEmail in the rest of the
function (referencing invitationData, invitationMethod, teamId, recipientEmail
in this file). Ensure every subsequent usage of invitationData.team_id becomes
teamId and invitationMethod.email becomes recipientEmail and include descriptive
error text per the defensive guideline.

In `@apps/e2e/tests/backend/endpoints/api/v1/team-invitations.test.ts`:
- Around line 995-1004: Update the two tests that assert a 500 on invalid
request parameters to expect a 4xx schema/validation error instead: in the tests
with descriptions "cannot specify both team_id and user_id" and "must specify
either team_id or user_id", change the assertion on listResponse.status from
.toBe(500) to assert a 4xx status (e.g. check listResponse.status >= 400 &&
listResponse.status < 500 or assert the specific validation error status your
backend returns such as 400 or SchemaError code). Keep the existing setup calls
(Auth.fastSignUp, Team.create) and the same niceBackendFetch request parameters,
only adjust the status expectation to validate client-side/schema validation
responses rather than a server error.

---

Duplicate comments:
In `@apps/backend/src/app/api/latest/team-invitations/`[id]/accept/route.tsx:
- Around line 84-88: Replace the internal StackAssertionError thrown when
matchingChannel is falsy with a user-facing KnownError so this user-driven email
mismatch returns a 4xx instead of a 500; specifically, in the accept invitation
handler (the block checking matchingChannel in
apps/backend/src/app/api/latest/team-invitations/[id]/accept/route.tsx), throw
new KnownError(...) with a clear message like "Cannot accept invitation: no
verified email matching the invitation's recipient email was found" (or reuse
the existing user-facing message) and preserve any existing error code/metadata
pattern used elsewhere for KnownError so callers receive a proper client error
response.
- Around line 52-143: The invitation can be consumed twice due to a TOCTOU: you
must move the verification code update into the same transaction that creates
the membership and make the update conditional on usedAt still being null to
ensure atomicity. Inside the retryTransaction callback (the function passed to
retryTransaction using tx from getPrismaClientForTenancy), perform a conditional
update on globalPrismaClient.verificationCode (or tx.verificationCode) using the
same composite key and include usedAt: null and expiresAt check in the WHERE,
then check the update result (rowsAffected or returned record) and throw
KnownErrors.VerificationCodeNotFound or a dedicated AlreadyUsed error if no row
was updated; only proceed with teamMembershipsCrudHandlers.adminCreate after the
conditional update succeeds (or do the update after ensuring oldMembership
absent but still within the same tx) so both membership creation and marking
used are in one atomic transaction using tx and the same verification code
constraints.

In `@apps/e2e/tests/backend/endpoints/api/v1/team-invitations.test.ts`:
- Around line 182-188: The test is asserting a 500 for a client validation
error; update the test "can't list invitations without team_id or user_id" to
expect a 4xx (e.g., 400 or 422) instead of 500 for requests to
`/api/v1/team-invitations` and adjust any server-side validation (the handler
that responds to GET /api/v1/team-invitations) to return the corresponding 4xx
when neither `team_id` nor `user_id` is provided; reference the test case name,
the niceBackendFetch call, and the endpoint `/api/v1/team-invitations` when
making the change so the assertion and server behavior align.

In `@packages/stack-shared/src/interface/client-interface.ts`:
- Around line 1212-1221: The acceptTeamInvitationById method interpolates
invitationId directly into the URL without encoding; change the path segment to
use the urlString helper (or encodeURIComponent) like the server-side
acceptServerTeamInvitationById does so that the invitationId is properly
URL-encoded before calling sendClientRequest; update the URL construction in
acceptTeamInvitationById to use urlString(invitationId) for the
`/team-invitations/{...}/accept` segment.

In `@packages/stack-shared/src/interface/server-interface.ts`:
- Around line 434-442: The return type of listServerUserTeamInvitations is
incorrect: change its declared Promise generic from
TeamInvitationCrud['Client']['Read'][] to TeamInvitationCrud['Server']['Read'][]
so server-only fields are preserved and consistent with
listServerTeamInvitations; locate the method listServerUserTeamInvitations
(which calls this.sendServerRequest and parses the JSON into
TeamInvitationCrud['Client']['List'] currently) and update both the method
signature and the parsed type to use TeamInvitationCrud['Server']['List'] /
TeamInvitationCrud['Server']['Read'][] as appropriate.

---

Nitpick comments:
In `@apps/backend/src/app/api/latest/team-invitations/`[id]/accept/route.tsx:
- Around line 3-4: The two separate import statements from "@/prisma-client"
should be consolidated into one; replace the duplicate imports by importing
getPrismaClientForTenancy, retryTransaction, and globalPrismaClient in a single
import declaration (referencing the symbols getPrismaClientForTenancy,
retryTransaction, globalPrismaClient) so there is only one import from
"@/prisma-client".

In `@apps/e2e/tests/backend/endpoints/api/v1/team-invitations.test.ts`:
- Line 852: The variable `inviter` returned from `Auth.fastSignUp()` is unused;
replace `const { userId: inviter } = await Auth.fastSignUp()` with a plain call
to `await Auth.fastSignUp()` (or destructure into `_` if you want to indicate
intentional ignore) in both test locations so the sign-in side-effect remains
but the unused `inviter` binding is removed; update the two occurrences that
call `Auth.fastSignUp()` accordingly.