feat: developer access permission gates webhooks/API keys/BYOK (v0.71.0)

Webhooks, self-serve API keys, and BYOK AI provider keys had zero
access gating -- any logged-in user, any tier. Adds users.isDeveloper
(boolean, admin-toggled in admin/users/[id] alongside role/tier),
checked via a single hasDeveloperAccess() (lib/permissions.ts) so a
future subscription-tier auto-grant is a one-line change there, not
a redesign across call sites.

requireDeveloper() (lib/api-auth.ts) wraps requireSession() with a
fresh isDeveloper check (same reasoning as requireAdmin re-querying
role: session.user's cookieCache can be up to 5 minutes stale) and
replaces requireSession in all 8 gated routes: webhooks CRUD +
deliveries + redeliver, api-keys CRUD, ai-keys CRUD.

Settings UI: the sidebar hides API Keys/Webhooks nav entries for
non-developers; those pages and the BYOK section of Settings -> AI
show a locked notice instead of the manager component when accessed
directly.

Migration grandfathers in anyone who already has a webhook, API key,
or BYOK key row -- ships as a new gate on existing features, not a
silent lockout of active integrations.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/web/app/api/v1/admin/users/[id]/route.ts

@@ -12,8 +12,8 @@ export async function PATCH(req: NextRequest, { params }: RouteContext) {
   if (response) return response;
 
   const { id } = await params;
-  const body = await req.json() as { role?: string; tier?: string };
-  const { role, tier } = body;
+  const body = await req.json() as { role?: string; tier?: string; isDeveloper?: boolean };
+  const { role, tier, isDeveloper } = body;
 
   const validRoles = ["user", "moderator", "admin"] as const;
   const validTiers = ["free", "pro", "family"] as const;
@@ -24,18 +24,22 @@ export async function PATCH(req: NextRequest, { params }: RouteContext) {
   if (tier !== undefined && !validTiers.includes(tier as typeof validTiers[number])) {
     return NextResponse.json({ error: "Invalid tier" }, { status: 400 });
   }
+  if (isDeveloper !== undefined && typeof isDeveloper !== "boolean") {
+    return NextResponse.json({ error: "Invalid isDeveloper" }, { status: 400 });
+  }
 
-  const updateData: Partial<{ role: "user" | "moderator" | "admin"; tier: "free" | "pro" | "family"; updatedAt: Date }> = {
+  const updateData: Partial<{ role: "user" | "moderator" | "admin"; tier: "free" | "pro" | "family"; isDeveloper: boolean; updatedAt: Date }> = {
     updatedAt: new Date(),
   };
   if (role) updateData.role = role as "user" | "moderator" | "admin";
   if (tier) updateData.tier = tier as "free" | "pro" | "family";
+  if (isDeveloper !== undefined) updateData.isDeveloper = isDeveloper;
 
   const [updated] = await db
     .update(users)
     .set(updateData)
     .where(eq(users.id, id))
-    .returning({ id: users.id, role: users.role, tier: users.tier });
+    .returning({ id: users.id, role: users.role, tier: users.tier, isDeveloper: users.isDeveloper });
 
   if (!updated) {
     return NextResponse.json({ error: "User not found" }, { status: 404 });
@@ -48,7 +52,7 @@ export async function PATCH(req: NextRequest, { params }: RouteContext) {
     action: "admin.user.update",
     targetType: "user",
     targetId: id,
-    metadata: JSON.stringify({ role, tier }),
+    metadata: JSON.stringify({ role, tier, isDeveloper }),
     createdAt: new Date(),
   });
 

apps/web/app/api/v1/ai-keys/[provider]/route.ts

@@ -1,11 +1,11 @@
 import { NextResponse } from "next/server";
 import { db, userAiKeys, eq, and } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 
 type Params = { params: Promise<{ provider: string }> };
 
 export async function DELETE(_req: Request, { params }: Params) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const { provider } = await params;

apps/web/app/api/v1/ai-keys/route.ts

@@ -1,7 +1,7 @@
 import { NextResponse } from "next/server";
 import { z } from "zod";
 import { db, userAiKeys, eq, and } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 import { encrypt } from "@/lib/encrypt";
 import { applyRateLimit } from "@/lib/rate-limit";
 
@@ -13,7 +13,7 @@ const PostSchema = z.object({
 });
 
 export async function GET() {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const keys = await db.query.userAiKeys.findMany({
@@ -25,7 +25,7 @@ export async function GET() {
 }
 
 export async function POST(req: Request) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const limited = await applyRateLimit(`rl:ai-keys:${session!.user.id}`, 5, 3600);

apps/web/app/api/v1/api-keys/[id]/route.ts

@@ -1,12 +1,12 @@
 import { NextRequest, NextResponse } from "next/server";
 import { db, apiKeys, eq, and } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 
 export async function DELETE(
   _req: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const { id } = await params;

apps/web/app/api/v1/api-keys/route.ts

@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
 import crypto from "node:crypto";
 import { z } from "zod";
 import { db, apiKeys, eq, sql } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 
 const CreateApiKeyBody = z.object({
   name: z.string().min(1).max(100),
@@ -10,7 +10,7 @@ const CreateApiKeyBody = z.object({
 });
 
 export async function GET() {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const rows = await db
@@ -28,7 +28,7 @@ export async function GET() {
 }
 
 export async function POST(req: NextRequest) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const body = await req.json() as unknown;

apps/web/app/api/v1/webhooks/[id]/__tests__/route.test.ts

@@ -4,7 +4,7 @@ import { NextRequest } from "next/server";
 const mockSession = { user: { id: "user-1" } };
 
 vi.mock("@/lib/api-auth", () => ({
-  requireSession: vi.fn(),
+  requireDeveloper: vi.fn(),
 }));
 
 vi.mock("@/lib/validate-webhook-url", () => ({
@@ -33,7 +33,7 @@ vi.mock("@epicure/db", () => ({
   and: vi.fn((...args) => ({ args, op: "and" })),
 }));
 
-const { requireSession } = await import("@/lib/api-auth");
+const { requireDeveloper } = await import("@/lib/api-auth");
 const { validateWebhookUrl } = await import("@/lib/validate-webhook-url");
 import { DELETE, PATCH } from "../route";
 
@@ -49,7 +49,7 @@ const ctx = { params: Promise.resolve({ id: "wh-1" }) };
 
 beforeEach(() => {
   vi.clearAllMocks();
-  vi.mocked(requireSession).mockResolvedValue({ session: mockSession as never, response: null });
+  vi.mocked(requireDeveloper).mockResolvedValue({ session: mockSession as never, response: null });
   vi.mocked(validateWebhookUrl).mockResolvedValue(null);
   mockSelectChain.limit.mockResolvedValue([{ id: "wh-1" }]);
 });

apps/web/app/api/v1/webhooks/[id]/deliveries/__tests__/route.test.ts

@@ -4,7 +4,7 @@ import { NextRequest } from "next/server";
 const mockSession = { user: { id: "user-1" } };
 
 vi.mock("@/lib/api-auth", () => ({
-  requireSession: vi.fn(),
+  requireDeveloper: vi.fn(),
 }));
 
 const { mockFindFirst, mockSelectChain } = vi.hoisted(() => {
@@ -29,21 +29,21 @@ vi.mock("@epicure/db", () => ({
   desc: vi.fn((a) => ({ a, op: "desc" })),
 }));
 
-const { requireSession } = await import("@/lib/api-auth");
+const { requireDeveloper } = await import("@/lib/api-auth");
 import { GET } from "../route";
 
 const ctx = { params: Promise.resolve({ id: "wh-1" }) };
 
 beforeEach(() => {
   vi.clearAllMocks();
-  vi.mocked(requireSession).mockResolvedValue({ session: mockSession as never, response: null });
+  vi.mocked(requireDeveloper).mockResolvedValue({ session: mockSession as never, response: null });
   mockFindFirst.mockResolvedValue({ id: "wh-1" });
   mockSelectChain.limit.mockResolvedValue([]);
 });
 
 describe("GET /api/v1/webhooks/[id]/deliveries", () => {
   it("returns 401 when not authenticated", async () => {
-    vi.mocked(requireSession).mockResolvedValue({
+    vi.mocked(requireDeveloper).mockResolvedValue({
       session: null,
       response: new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 }),
     } as never);

apps/web/app/api/v1/webhooks/[id]/deliveries/route.ts

@@ -1,11 +1,11 @@
 import { NextRequest, NextResponse } from "next/server";
 import { db, webhooks, webhookDeliveries, eq, and, desc } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 
 type Params = { params: Promise<{ id: string }> };
 
 export async function GET(_req: NextRequest, { params }: Params) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const { id } = await params;

apps/web/app/api/v1/webhooks/[id]/redeliver/__tests__/route.test.ts

@@ -4,7 +4,7 @@ import { NextRequest } from "next/server";
 const mockSession = { user: { id: "user-1" } };
 
 vi.mock("@/lib/api-auth", () => ({
-  requireSession: vi.fn(),
+  requireDeveloper: vi.fn(),
 }));
 
 vi.mock("@/lib/webhooks", () => ({
@@ -29,7 +29,7 @@ vi.mock("@epicure/db", () => ({
   and: vi.fn((...args) => ({ args, op: "and" })),
 }));
 
-const { requireSession } = await import("@/lib/api-auth");
+const { requireDeveloper } = await import("@/lib/api-auth");
 const { dispatchWebhook } = await import("@/lib/webhooks");
 import { POST } from "../route";
 
@@ -47,7 +47,7 @@ const ctx = { params: Promise.resolve({ id: "wh-1" }) };
 
 beforeEach(() => {
   vi.clearAllMocks();
-  vi.mocked(requireSession).mockResolvedValue({ session: mockSession as never, response: null });
+  vi.mocked(requireDeveloper).mockResolvedValue({ session: mockSession as never, response: null });
   mockWebhookFindFirst.mockResolvedValue({ id: "wh-1" });
   mockDeliveryFindFirst.mockResolvedValue({
     id: VALID_DELIVERY_ID,
@@ -58,7 +58,7 @@ beforeEach(() => {
 
 describe("POST /api/v1/webhooks/[id]/redeliver", () => {
   it("returns 401 when not authenticated", async () => {
-    vi.mocked(requireSession).mockResolvedValue({
+    vi.mocked(requireDeveloper).mockResolvedValue({
       session: null,
       response: new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 }),
     } as never);

apps/web/app/api/v1/webhooks/[id]/redeliver/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { z } from "zod";
 import { db, webhooks, webhookDeliveries, eq, and } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 import { dispatchWebhook, type WebhookEvent } from "@/lib/webhooks";
 
 const Schema = z.object({ deliveryId: z.string().uuid() });
@@ -9,7 +9,7 @@ const Schema = z.object({ deliveryId: z.string().uuid() });
 type Params = { params: Promise<{ id: string }> };
 
 export async function POST(req: NextRequest, { params }: Params) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const { id } = await params;

apps/web/app/api/v1/webhooks/[id]/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { z } from "zod";
 import { db, webhooks, eq, and } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 import { validateWebhookUrl } from "@/lib/validate-webhook-url";
 import { WEBHOOK_EVENTS } from "@/lib/webhooks";
 
@@ -15,7 +15,7 @@ export async function DELETE(
   _req: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const { id } = await params;
@@ -41,7 +41,7 @@ export async function PATCH(
   req: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const { id } = await params;

apps/web/app/api/v1/webhooks/__tests__/route.test.ts

@@ -4,7 +4,7 @@ import { NextRequest } from "next/server";
 const mockSession = { user: { id: "user-1" } };
 
 vi.mock("@/lib/api-auth", () => ({
-  requireSession: vi.fn(),
+  requireDeveloper: vi.fn(),
 }));
 
 vi.mock("@/lib/validate-webhook-url", () => ({
@@ -28,7 +28,7 @@ vi.mock("@epicure/db", () => ({
   eq: vi.fn((a, b) => ({ a, b, op: "eq" })),
 }));
 
-const { requireSession } = await import("@/lib/api-auth");
+const { requireDeveloper } = await import("@/lib/api-auth");
 const { validateWebhookUrl } = await import("@/lib/validate-webhook-url");
 import { GET, POST } from "../route";
 
@@ -42,14 +42,14 @@ function makeRequest(method: string, body?: unknown) {
 
 beforeEach(() => {
   vi.clearAllMocks();
-  vi.mocked(requireSession).mockResolvedValue({ session: mockSession as never, response: null });
+  vi.mocked(requireDeveloper).mockResolvedValue({ session: mockSession as never, response: null });
   vi.mocked(validateWebhookUrl).mockResolvedValue(null);
   mockSelectChain.where.mockResolvedValue([]);
 });
 
 describe("GET /api/v1/webhooks", () => {
   it("returns 401 when not authenticated", async () => {
-    vi.mocked(requireSession).mockResolvedValue({
+    vi.mocked(requireDeveloper).mockResolvedValue({
       session: null,
       response: new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 }),
     } as never);
@@ -82,7 +82,7 @@ describe("POST /api/v1/webhooks", () => {
   });
 
   it("returns 401 when not authenticated", async () => {
-    vi.mocked(requireSession).mockResolvedValue({
+    vi.mocked(requireDeveloper).mockResolvedValue({
       session: null,
       response: new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 }),
     } as never);

apps/web/app/api/v1/webhooks/route.ts

@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
 import crypto from "node:crypto";
 import { z } from "zod";
 import { db, webhooks, eq } from "@epicure/db";
-import { requireSession } from "@/lib/api-auth";
+import { requireDeveloper } from "@/lib/api-auth";
 import { validateWebhookUrl } from "@/lib/validate-webhook-url";
 import { WEBHOOK_EVENTS } from "@/lib/webhooks";
 import { encrypt } from "@/lib/encrypt";
@@ -19,7 +19,7 @@ const UpdateWebhookBody = z.object({
 });
 
 export async function GET() {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const rows = await db
@@ -38,7 +38,7 @@ export async function GET() {
 }
 
 export async function POST(req: NextRequest) {
-  const { session, response } = await requireSession();
+  const { session, response } = await requireDeveloper();
   if (response) return response;
 
   const body = await req.json() as unknown;