feat(web): add audit log entries for org membership changes

[brendan-kellam]

Summary

Adds three new audit actions so the membership lifecycle is fully captured in the audit log:

• org.member_added — fires from all five UserToOrg-creation paths:
  • Initial owner on first signup (onCreateUser, alongside the existing user.owner_created)
  • Auto-add on signup when memberApprovalRequired = false (previously silent)
  • Magic invite-link join via joinOrganization (previously silent)
  • Email invite redemption (alongside the existing user.invite_accepted)
  • Join-request approval (alongside the existing user.join_request_approved)
• org.member_removed — fires when an admin removes a member via Settings → Members.
• org.member_left — fires when a user leaves the org themselves.

All three use a consistent (actor=user, target=user) shape so the full membership history can be reconstructed with one filter per state transition (org.member_added / org.member_removed / org.member_left). The existing per-path audits (user.invite_accepted, user.join_request_approved, user.owner_created) are preserved as semantic detail — they describe how a user joined, while org.member_added records that they joined.

The metadata.message on each event records the specific path (initial owner, no-approval signup, invite link, invite ID, approving admin) so detail isn't lost.

createGuestUser is intentionally not audited — it upserts the singleton system Guest user, not a real membership grant.

Test plan

• Sign up as the very first user → expect user.owner_created + org.member_added (target = self).
• With memberApprovalRequired = false, sign up a second user via SSO → expect org.member_added (target = self).
• Enable invite-link join, have a user join via the link → expect org.member_added (target = self).
• Send an email invite, redeem it → expect user.invite_accepted + org.member_added.
• As an admin, approve a pending join request → expect user.join_request_approved + org.member_added (actor = admin, target = approved user).
• As an admin, remove a member via Settings → Members → expect org.member_removed.
• As a non-owner member, leave the org → expect org.member_left.
• Confirm org.member_removed does not fire if the removal transaction fails (e.g. last-owner guard).
• Verify the docs table at docs/docs/configuration/audit-logs.mdx lists the three new actions.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added three audit action types for organization member lifecycle: org.member_added, org.member_removed, org.member_left. These events are now recorded across member approval, invite acceptance, removals, voluntary departures, and single-tenant provisioning flows.

• Documentation

  • Updated audit logs docs to include the new membership action types with actor/target details.

• Chores

  • Added entry to CHANGELOG for the new audit actions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 75b17d36-4823-4df3-9c9e-fcf40270f23e

📥 Commits

Reviewing files that changed from the base of the PR and between 073421a and abdfd9f.

📒 Files selected for processing (1)

• packages/web/src/actions.ts

---

Walkthrough

Adds three organization membership audit events (org.member_added, org.member_removed, org.member_left) and instruments membership-related flows to emit those audits across account-approval, invite/join, member removal/leave, and single-tenant provisioning paths.

Changes

Cohort / File(s)	Summary
Documentation CHANGELOG.md, docs/docs/configuration/audit-logs.mdx	Added Unreleased changelog entry and documented three new audit action types: org.member_added, org.member_removed, org.member_left.
Account Request Approval packages/web/src/actions.ts	Emits org.member_added after approveAccountRequest completes; reorders email send to occur after audit and wraps send in try/catch.
Invite & Join Flows packages/web/src/app/invite/actions.ts	Emits org.member_added in joinOrganization and redeemInvite after successful membership changes, with contextual metadata (invite link or inviteId).
Member Management packages/web/src/features/userManagement/actions.ts	Calls audit service in removeMemberFromOrg and leaveOrg to create org.member_removed and org.member_left records after transaction/guard checks.
Single-Tenant Provisioning packages/web/src/lib/authUtils.ts	Creates org.member_added audit events during onCreateUser for initial owner and for subsequent member additions when approval is not required (uses single-tenant org ID).

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ServerAction as Server Action Handler
  participant AuditSvc as AuditService
  participant DB as Database
  participant Email as Email/SMTP

  Client->>ServerAction: trigger approveAccountRequest / join / redeem / leave / remove
  ServerAction->>DB: perform membership change transaction
  DB-->>ServerAction: transaction result
  ServerAction->>AuditSvc: createAudit(action: org.member_*)
  AuditSvc-->>DB: persist audit record
  AuditSvc-->>ServerAction: confirmation
  ServerAction->>Email: send notification (if applicable)
  Email-->>ServerAction: send result / errors
  ServerAction-->>Client: response

Loading

Possibly related PRs

• feat(web): add multi-owner support with promote/demote actions #988: Modifies organization membership flows and related audit/event logging in the same member-management code paths.
• feat(web): add PostHog events for user creation and Ask GitHub login wall #933: Updates packages/web/src/lib/authUtils.ts user-provisioning logic to emit events on creation (related to the onCreateUser audit additions).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(web): add audit log entries for org membership changes' accurately and concisely describes the main change across all files—adding audit logging for organization member lifecycle events (added, removed, left).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch brendan/audit-org-membership-changes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/docs/configuration/audit-logs.mdx (1)

148-150: ⚡ Quick win

Clarify actor/target semantics for these new membership events.

The user / user rows are accurate on types, but org.member_added and org.member_removed do not always use the same user ID on both sides. In the approval/removal flows the actor is the admin and the target is the affected member, so a short note here would prevent readers from inferring actorId === targetId for every one of these events.

🤖 Prompt for AI Agents

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

In `@docs/docs/configuration/audit-logs.mdx` around lines 148 - 150, Update the
docs for the membership events (`org.member_added`, `org.member_removed`,
`org.member_left`) to clarify actor vs target semantics: explicitly state that
for `org.member_added` and `org.member_removed` the actor is typically the admin
performing the approval/removal and the target is the affected member (so
actorId != targetId), whereas for `org.member_left` the actor and target are the
same user (self-initiated, actorId === targetId); add a short footnote or
parenthetical note next to those table rows so readers don’t assume actorId ===
targetId for all three events.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@packages/web/src/actions.ts`:
- Around line 1051-1059: The approval audit writes (calls to
auditService.createAudit for "user.join_request_approved" and
"org.member_added") must be performed before the email side-effect (the call(s)
to render() and sendMail()), so move the auditService.createAudit calls to occur
immediately after addUserToOrganization() (and before render/sendMail), or
alternatively wrap render/sendMail in a try/catch that logs/suppresses email
errors without reverting the endpoint error response; update the code paths
using requestId, request.requestedById, user.id, org.id and ensure the
user.join_request_approved and org.member_added audits are created prior to any
potential throw from render()/sendMail().

---

Nitpick comments:
In `@docs/docs/configuration/audit-logs.mdx`:
- Around line 148-150: Update the docs for the membership events
(`org.member_added`, `org.member_removed`, `org.member_left`) to clarify actor
vs target semantics: explicitly state that for `org.member_added` and
`org.member_removed` the actor is typically the admin performing the
approval/removal and the target is the affected member (so actorId != targetId),
whereas for `org.member_left` the actor and target are the same user
(self-initiated, actorId === targetId); add a short footnote or parenthetical
note next to those table rows so readers don’t assume actorId === targetId for
all three events.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b4ac4407-4234-4546-aac8-a8e03407825d

📥 Commits

Reviewing files that changed from the base of the PR and between ff41d83 and 073421a.

📒 Files selected for processing (6)

• CHANGELOG.md
• docs/docs/configuration/audit-logs.mdx
• packages/web/src/actions.ts
• packages/web/src/app/invite/actions.ts
• packages/web/src/features/userManagement/actions.ts
• packages/web/src/lib/authUtils.ts