Feature/team access audit log (#733)

* feat: add team access management (admin/developer roles)

Adds /dashboard/settings/team and /api/team (GET/POST/DELETE), backed
by a mock store in dev and proxied to mux-backend when
NEXT_PUBLIC_API_URL is configured. Admins can add/remove members;
developers get a read-only view. No invite-email flow yet — members
are added directly, matching current scope.

* fix: never serve mock activity feed in production

/api/activity fell back to the mock-transaction heuristic
unconditionally, unlike /api/wallets and friends, so a production
deploy with no NEXT_PUBLIC_API_URL configured would silently serve
fabricated activity instead of a 503. Adds the same
isMockFallbackAllowed() gate used elsewhere, and records mock activity
into a small append-only in-memory store (src/lib/audit/log.ts) as a
placeholder shape for the real backend-owned immutable audit log.

Author: martinzhames

README.md

@@ -210,5 +210,10 @@ stay easy to find and don't clutter the repo root as features evolve.
 
 * Per-key usage analytics
 * Webhooks and notifications for SDK events
-* Team access management
-* Audit logs for all wallet and API activity
+* ~~Team access management~~ — basic admin/developer member management is in
+  at `/dashboard/settings/team` (`/api/team`); see
+  [`docs/team-access-and-audit-log.md`](docs/team-access-and-audit-log.md)
+* ~~Audit logs for all wallet and API activity~~ — `/api/activity` now
+  follows the same production/mock split as the rest of the app instead of
+  always serving mock data; see
+  [`docs/team-access-and-audit-log.md`](docs/team-access-and-audit-log.md)

docs/team-access-and-audit-log.md

@@ -0,0 +1,30 @@
+# Team access management & activity audit log
+
+## Team access
+
+`GET /api/team` and `POST /api/team` (and `DELETE /api/team/[id]`) manage the
+list of people with access to this project's dashboard. Each member has a
+`role` of `"admin"` or `"developer"` — the login role already returned by
+`AuthContext`'s `AuthUser.role`. Only `admin` can add or remove members;
+`developer` gets a read-only view. There is no email-invite flow: an admin
+adds a member directly by name/email/role.
+
+The management UI lives at `/dashboard/settings/team`.
+
+Like the other API routes in this app, `/api/team` proxies to the configured
+backend (`NEXT_PUBLIC_API_URL` or legacy aliases) when set, falls back to an
+in-repo mock store (`src/mock-data/team.ts`) for local dev/CI when no backend
+is configured, and returns `503 backend_unavailable` instead of mock data
+when running with `NODE_ENV=production` and no backend configured — see
+`isMockFallbackAllowed()` in `src/lib/api/config.ts`.
+
+## Activity / audit log
+
+`GET /api/activity` previously fell back to a mock-transaction heuristic
+regardless of `NODE_ENV`, unlike `/api/wallets` and friends. It now follows
+the same production gate as the rest of the app: with a backend configured,
+it proxies to the backend's real event/activity feed; with no backend and
+`NODE_ENV=production`, it returns `503 backend_unavailable` instead of mock
+data; only outside production does it fall back to mock data, which it now
+also appends to an in-memory append-only store (`src/lib/audit/log.ts`) as a
+placeholder shape for the real immutable audit log the backend should serve.

src/app/api/activity/route.production.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Regression coverage for the production/mock split on GET /api/activity.
+ *
+ * Before this test, the mock activity fallback ran unconditionally
+ * regardless of NODE_ENV, so a production deployment with no
+ * NEXT_PUBLIC_API_URL configured would silently serve fabricated activity
+ * items instead of failing loudly. See src/lib/api/runtimeMode.ts /
+ * isMockFallbackAllowed() for the pattern this mirrors from
+ * src/app/api/wallets/route.ts.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GET } from "./route";
+
+describe("GET /api/activity in production without a configured backend", () => {
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it("returns 503 instead of falling back to mock activity data", async () => {
+		vi.stubEnv("NEXT_PUBLIC_API_URL", "");
+		vi.stubEnv("NEXT_PUBLIC_MUX_API_URL", "");
+		vi.stubEnv("NEXT_PUBLIC_API_BASE", "");
+		vi.stubEnv("NODE_ENV", "production");
+
+		const res = await GET();
+		expect(res.status).toBe(503);
+		const body = await res.json();
+		expect(body.error).toBe("backend_unavailable");
+	});
+});

src/app/api/activity/route.ts

@@ -1,5 +1,6 @@
 import { NextResponse } from "next/server";
-import { getApiBaseUrl, getUpstreamAuthHeaders } from "@/lib/api/config";
+import { getApiBaseUrl, getUpstreamAuthHeaders, isMockFallbackAllowed } from "@/lib/api/config";
+import { appendAuditLog, getAuditLog } from "@/lib/audit/log";
 import { mockTransactions } from "@/mock-data/transactions";
 import type { Transaction } from "@/types/transaction";
 
@@ -72,10 +73,26 @@ export async function GET() {
 		}
 	}
 
-	// --- Mock fallback (no NEXT_PUBLIC_API_URL set) ---
-	// Synthesizes activity items from mock transaction data; used for local
-	// dev / CI only when no backend is configured.
-	const activities = mockTransactions.map(mapTransactionToActivity);
+	if (!isMockFallbackAllowed()) {
+		return NextResponse.json(
+			{
+				error: "backend_unavailable",
+				message:
+					"No activity backend is configured for this production deployment. Set NEXT_PUBLIC_API_URL.",
+			},
+			{ status: 503 },
+		);
+	}
+
+	// --- Mock fallback (no NEXT_PUBLIC_API_URL set, non-production only) ---
+	// Synthesizes activity items from mock transaction data and records them
+	// into the in-memory audit log; used for local dev / CI only when no
+	// backend is configured. See src/lib/audit/log.ts.
+	if (getAuditLog().length === 0) {
+		for (const activity of mockTransactions.map(mapTransactionToActivity)) {
+			appendAuditLog(activity);
+		}
+	}
 
-	return NextResponse.json({ data: activities });
+	return NextResponse.json({ data: getAuditLog() });
 }

src/app/api/team/[id]/route.ts

@@ -0,0 +1,65 @@
+import { NextResponse } from "next/server";
+import {
+	getApiBaseUrl,
+	getUpstreamAuthHeaders,
+	isMockFallbackAllowed,
+} from "@/lib/api/config";
+import { removeTeamMember } from "@/mock-data/team";
+
+/**
+ * DELETE /api/team/[id]
+ *
+ * Removes a team member. Proxies to the backend when configured; otherwise
+ * falls back to the in-repo mock store outside production only.
+ */
+export async function DELETE(
+	_request: Request,
+	{ params }: { params: Promise<{ id: string }> },
+) {
+	const { id } = await params;
+	const backendUrl = getApiBaseUrl();
+
+	if (backendUrl) {
+		try {
+			const upstream = await fetch(`${backendUrl}/team/${id}`, {
+				method: "DELETE",
+				headers: {
+					"content-type": "application/json",
+					...getUpstreamAuthHeaders(),
+				},
+			});
+
+			if (!upstream.ok) {
+				return NextResponse.json(
+					{ error: "Unable to remove team member on the backend" },
+					{ status: upstream.status || 502 },
+				);
+			}
+
+			return NextResponse.json({ ok: true });
+		} catch {
+			return NextResponse.json(
+				{ error: "Unable to reach the team backend" },
+				{ status: 502 },
+			);
+		}
+	}
+
+	if (!isMockFallbackAllowed()) {
+		return NextResponse.json(
+			{
+				error: "backend_unavailable",
+				message:
+					"No team backend is configured for this production deployment. Set NEXT_PUBLIC_API_URL.",
+			},
+			{ status: 503 },
+		);
+	}
+
+	// --- Mock fallback (no NEXT_PUBLIC_API_URL set, non-production only) ---
+	const removed = removeTeamMember(id);
+	if (!removed) {
+		return NextResponse.json({ error: "Member not found" }, { status: 404 });
+	}
+	return NextResponse.json({ ok: true });
+}

src/app/api/team/route.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Tests for GET/POST /api/team.
+ *
+ * Covers:
+ * - Mock fallback list/add in non-production when no backend is configured
+ * - Proxies to the backend when NEXT_PUBLIC_API_URL is set
+ * - Never falls back to mock team data in a production build — fails
+ *   loudly with 503 instead, matching the pattern in
+ *   src/app/api/wallets/route.ts / isMockFallbackAllowed().
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GET, POST } from "./route";
+
+function postRequest(body: unknown): Request {
+	return new Request("http://localhost/api/team", {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body),
+	});
+}
+
+describe("/api/team", () => {
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		vi.unstubAllGlobals();
+	});
+
+	describe("mock fallback (no NEXT_PUBLIC_API_URL, non-production)", () => {
+		it("lists mock team members", async () => {
+			vi.stubEnv("NEXT_PUBLIC_API_URL", "");
+			vi.stubEnv("NODE_ENV", "test");
+
+			const res = await GET();
+			expect(res.status).toBe(200);
+			const body = await res.json();
+			expect(Array.isArray(body.data)).toBe(true);
+			expect(body.data.length).toBeGreaterThan(0);
+		});
+
+		it("rejects an invalid role", async () => {
+			vi.stubEnv("NEXT_PUBLIC_API_URL", "");
+			vi.stubEnv("NODE_ENV", "test");
+
+			const res = await POST(
+				postRequest({ name: "Test", email: "t@example.com", role: "owner" }),
+			);
+			expect(res.status).toBe(400);
+		});
+	});
+
+	describe("backend proxy (NEXT_PUBLIC_API_URL is set)", () => {
+		it("proxies GET to the backend", async () => {
+			vi.stubEnv("NEXT_PUBLIC_API_URL", "https://api.example.com");
+			const fetchMock = vi.fn().mockResolvedValue({
+				ok: true,
+				json: () => Promise.resolve([{ id: "m1", role: "admin" }]),
+			});
+			vi.stubGlobal("fetch", fetchMock);
+
+			const res = await GET();
+			expect(res.status).toBe(200);
+			expect(fetchMock).toHaveBeenCalledWith(
+				"https://api.example.com/team",
+				expect.any(Object),
+			);
+		});
+	});
+
+	describe("production without a configured backend", () => {
+		it("returns 503 instead of silently serving mock team members", async () => {
+			vi.stubEnv("NEXT_PUBLIC_API_URL", "");
+			vi.stubEnv("NEXT_PUBLIC_MUX_API_URL", "");
+			vi.stubEnv("NEXT_PUBLIC_API_BASE", "");
+			vi.stubEnv("NODE_ENV", "production");
+
+			const res = await GET();
+			expect(res.status).toBe(503);
+			const body = await res.json();
+			expect(body.error).toBe("backend_unavailable");
+		});
+	});
+});