feat: self-serve developer access for paid tiers, split BYOK into its own permission (v0.72.0)

Splits what was one isDeveloper flag (gating webhooks, API keys, AND
BYOK together) into two independent permissions:

- isDeveloper (webhooks + self-serve API keys): admin-toggled as
  before, but now ALSO self-serve -- PATCH /api/v1/users/me/developer-access
  lets any paid-tier (tier !== "free") user turn it on themselves, no
  added fee. Free tier still needs an admin grant. Turning it off is
  always self-serve regardless of tier, since revoking your own
  access needs no gatekeeping. canSelfServeDeveloperAccess() in
  lib/permissions.ts is the single check for "is this tier eligible."

- isByokEnabled (BYOK AI provider keys): new column, admin-only, no
  self-serve path at all -- routing real AI provider spend through
  Epicure on the user's own key warrants a manual admin check-in that
  webhooks/API access don't need. requireByok() replaces
  requireDeveloper() on the three ai-keys routes.

Migration adds is_byok_enabled and grandfathers in anyone who already
has a BYOK key configured (the earlier grandfather migration only
covered the combined isDeveloper flag, which BYOK no longer reads).

Settings UI: webhooks/API-keys pages show a self-serve "Enable"
toggle for paid-tier non-developers instead of the locked notice
(still shown to free-tier users), plus a "Disable developer access"
link once enabled. Settings -> AI's BYOK section now checks
isByokEnabled instead of isDeveloper -- unaffected by the self-serve
change, still fully admin-gated.

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

apps/web/app/(app)/settings/ai/page.tsx

@@ -28,7 +28,7 @@ export default async function AiSettingsPage() {
     }),
     // Tier comes from the DB, not the (up to 5-minute-stale) session cookie
     // cache, so a just-changed tier's limits show up immediately here.
-    db.query.users.findFirst({ where: eq(users.id, session.user.id), columns: { tier: true, isDeveloper: true } }),
+    db.query.users.findFirst({ where: eq(users.id, session.user.id), columns: { tier: true, isByokEnabled: true } }),
   ]);
 
   const [tierDef, usage, recipeCount, storageUsedMb] = await Promise.all([
@@ -81,10 +81,10 @@ export default async function AiSettingsPage() {
             {m.settings.byok.description}
           </p>
         </div>
-        {dbUser?.isDeveloper ? (
+        {dbUser?.isByokEnabled ? (
           <ByokManager initialKeys={aiKeys.map((k) => k.provider)} />
         ) : (
-          <DeveloperLockedNotice message={m.settings.developerLockedNotice} />
+          <DeveloperLockedNotice message={m.settings.byokLockedNotice} />
         )}
       </section>
 

apps/web/app/(app)/settings/api-keys/page.tsx

@@ -6,6 +6,9 @@ import { auth } from "@/lib/auth/server";
 import { db, apiKeys, users, eq } from "@epicure/db";
 import { ApiKeysManager } from "@/components/settings/api-keys-manager";
 import { DeveloperLockedNotice } from "@/components/settings/developer-locked-notice";
+import { DeveloperAccessToggle } from "@/components/settings/developer-access-toggle";
+import { DisableDeveloperAccessButton } from "@/components/settings/disable-developer-access-button";
+import { canSelfServeDeveloperAccess } from "@/lib/permissions";
 import { getMessages } from "@/lib/i18n/server";
 
 export const metadata: Metadata = {};
@@ -15,7 +18,7 @@ export default async function ApiKeysPage() {
   if (!session) return null;
   const m = getMessages((session.user as { locale?: string }).locale);
 
-  const dbUser = (await db.select({ isDeveloper: users.isDeveloper }).from(users).where(eq(users.id, session.user.id)).limit(1))[0];
+  const dbUser = (await db.select({ isDeveloper: users.isDeveloper, tier: users.tier }).from(users).where(eq(users.id, session.user.id)).limit(1))[0];
 
   const keys = dbUser?.isDeveloper
     ? await db
@@ -47,17 +50,25 @@ export default async function ApiKeysPage() {
             {m.settings.apiKeysPage.docsLink}
           </Link>
         </div>
-        {!dbUser?.isDeveloper && <DeveloperLockedNotice message={m.settings.developerLockedNotice} />}
+        {!dbUser?.isDeveloper && dbUser && canSelfServeDeveloperAccess(dbUser) && (
+          <DeveloperAccessToggle message={m.settings.developerSelfServeNotice} />
+        )}
+        {!dbUser?.isDeveloper && (!dbUser || !canSelfServeDeveloperAccess(dbUser)) && (
+          <DeveloperLockedNotice message={m.settings.developerLockedNotice} />
+        )}
         {dbUser?.isDeveloper && (
-          <ApiKeysManager
-            initialKeys={keys.map((k) => ({
-              id: k.id,
-              name: k.name,
-              scope: k.scope,
-              lastUsedAt: k.lastUsedAt ? k.lastUsedAt.toISOString() : null,
-              createdAt: k.createdAt.toISOString(),
-            }))}
-          />
+          <>
+            <ApiKeysManager
+              initialKeys={keys.map((k) => ({
+                id: k.id,
+                name: k.name,
+                scope: k.scope,
+                lastUsedAt: k.lastUsedAt ? k.lastUsedAt.toISOString() : null,
+                createdAt: k.createdAt.toISOString(),
+              }))}
+            />
+            <DisableDeveloperAccessButton />
+          </>
         )}
       </section>
     </div>

apps/web/app/(app)/settings/layout.tsx

@@ -3,14 +3,16 @@ import { auth } from "@/lib/auth/server";
 import { db, users, eq } from "@epicure/db";
 import { SettingsSidebar } from "@/components/settings/settings-sidebar";
 import { getMessages } from "@/lib/i18n/server";
+import { canSelfServeDeveloperAccess } from "@/lib/permissions";
 
 export default async function SettingsLayout({ children }: { children: React.ReactNode }) {
   const session = await auth.api.getSession({ headers: await headers() });
   const m = getMessages((session?.user as { locale?: string })?.locale);
 
   const dbUser = session
-    ? (await db.select({ isDeveloper: users.isDeveloper }).from(users).where(eq(users.id, session.user.id)).limit(1))[0]
+    ? (await db.select({ isDeveloper: users.isDeveloper, tier: users.tier }).from(users).where(eq(users.id, session.user.id)).limit(1))[0]
     : undefined;
+  const showDeveloperNav = !!dbUser && (dbUser.isDeveloper || canSelfServeDeveloperAccess(dbUser));
 
   return (
     <div className="max-w-5xl mx-auto">
@@ -19,7 +21,7 @@ export default async function SettingsLayout({ children }: { children: React.Rea
         <p className="text-muted-foreground mt-1">{m.settings.subtitle}</p>
       </div>
       <div className="flex flex-col md:flex-row gap-4 md:gap-8 md:items-start">
-        <SettingsSidebar isDeveloper={dbUser?.isDeveloper ?? false} />
+        <SettingsSidebar showDeveloperNav={showDeveloperNav} />
         <main className="flex-1 min-w-0 space-y-6">{children}</main>
       </div>
     </div>

apps/web/app/(app)/settings/webhooks/page.tsx

@@ -4,6 +4,9 @@ import { auth } from "@/lib/auth/server";
 import { db, webhooks, users, eq } from "@epicure/db";
 import { WebhooksManager } from "@/components/settings/webhooks-manager";
 import { DeveloperLockedNotice } from "@/components/settings/developer-locked-notice";
+import { DeveloperAccessToggle } from "@/components/settings/developer-access-toggle";
+import { DisableDeveloperAccessButton } from "@/components/settings/disable-developer-access-button";
+import { canSelfServeDeveloperAccess } from "@/lib/permissions";
 import { getMessages } from "@/lib/i18n/server";
 
 export const metadata: Metadata = {};
@@ -13,7 +16,7 @@ export default async function WebhooksPage() {
   if (!session) return null;
   const m = getMessages((session.user as { locale?: string }).locale);
 
-  const dbUser = (await db.select({ isDeveloper: users.isDeveloper }).from(users).where(eq(users.id, session.user.id)).limit(1))[0];
+  const dbUser = (await db.select({ isDeveloper: users.isDeveloper, tier: users.tier }).from(users).where(eq(users.id, session.user.id)).limit(1))[0];
 
   const rows = dbUser?.isDeveloper
     ? await db
@@ -37,17 +40,25 @@ export default async function WebhooksPage() {
             {m.settings.webhooksPage.description}
           </p>
         </div>
-        {!dbUser?.isDeveloper && <DeveloperLockedNotice message={m.settings.developerLockedNotice} />}
+        {!dbUser?.isDeveloper && dbUser && canSelfServeDeveloperAccess(dbUser) && (
+          <DeveloperAccessToggle message={m.settings.developerSelfServeNotice} />
+        )}
+        {!dbUser?.isDeveloper && (!dbUser || !canSelfServeDeveloperAccess(dbUser)) && (
+          <DeveloperLockedNotice message={m.settings.developerLockedNotice} />
+        )}
         {dbUser?.isDeveloper && (
-          <WebhooksManager
-            initialWebhooks={rows.map((w) => ({
-              id: w.id,
-              url: w.url,
-              events: w.events,
-              active: w.active,
-              createdAt: w.createdAt.toISOString(),
-            }))}
-          />
+          <>
+            <WebhooksManager
+              initialWebhooks={rows.map((w) => ({
+                id: w.id,
+                url: w.url,
+                events: w.events,
+                active: w.active,
+                createdAt: w.createdAt.toISOString(),
+              }))}
+            />
+            <DisableDeveloperAccessButton />
+          </>
         )}
       </section>
     </div>

apps/web/app/admin/users/[id]/page.tsx

@@ -102,7 +102,7 @@ export default async function AdminUserDetailPage({ params }: PageProps) {
             <CardTitle className="text-base">Edit Role &amp; Tier</CardTitle>
           </CardHeader>
           <CardContent>
-            <UserEditor userId={user.id} currentRole={user.role} currentTier={user.tier} currentIsDeveloper={user.isDeveloper} />
+            <UserEditor userId={user.id} currentRole={user.role} currentTier={user.tier} currentIsDeveloper={user.isDeveloper} currentIsByokEnabled={user.isByokEnabled} />
           </CardContent>
         </Card>
 

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; isDeveloper?: boolean };
-  const { role, tier, isDeveloper } = body;
+  const body = await req.json() as { role?: string; tier?: string; isDeveloper?: boolean; isByokEnabled?: boolean };
+  const { role, tier, isDeveloper, isByokEnabled } = body;
 
   const validRoles = ["user", "moderator", "admin"] as const;
   const validTiers = ["free", "pro", "family"] as const;
@@ -27,19 +27,23 @@ export async function PATCH(req: NextRequest, { params }: RouteContext) {
   if (isDeveloper !== undefined && typeof isDeveloper !== "boolean") {
     return NextResponse.json({ error: "Invalid isDeveloper" }, { status: 400 });
   }
+  if (isByokEnabled !== undefined && typeof isByokEnabled !== "boolean") {
+    return NextResponse.json({ error: "Invalid isByokEnabled" }, { status: 400 });
+  }
 
-  const updateData: Partial<{ role: "user" | "moderator" | "admin"; tier: "free" | "pro" | "family"; isDeveloper: boolean; updatedAt: Date }> = {
+  const updateData: Partial<{ role: "user" | "moderator" | "admin"; tier: "free" | "pro" | "family"; isDeveloper: boolean; isByokEnabled: 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;
+  if (isByokEnabled !== undefined) updateData.isByokEnabled = isByokEnabled;
 
   const [updated] = await db
     .update(users)
     .set(updateData)
     .where(eq(users.id, id))
-    .returning({ id: users.id, role: users.role, tier: users.tier, isDeveloper: users.isDeveloper });
+    .returning({ id: users.id, role: users.role, tier: users.tier, isDeveloper: users.isDeveloper, isByokEnabled: users.isByokEnabled });
 
   if (!updated) {
     return NextResponse.json({ error: "User not found" }, { status: 404 });
@@ -52,7 +56,7 @@ export async function PATCH(req: NextRequest, { params }: RouteContext) {
     action: "admin.user.update",
     targetType: "user",
     targetId: id,
-    metadata: JSON.stringify({ role, tier, isDeveloper }),
+    metadata: JSON.stringify({ role, tier, isDeveloper, isByokEnabled }),
     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 { requireDeveloper } from "@/lib/api-auth";
+import { requireByok } from "@/lib/api-auth";
 
 type Params = { params: Promise<{ provider: string }> };
 
 export async function DELETE(_req: Request, { params }: Params) {
-  const { session, response } = await requireDeveloper();
+  const { session, response } = await requireByok();
   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 { requireDeveloper } from "@/lib/api-auth";
+import { requireByok } 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 requireDeveloper();
+  const { session, response } = await requireByok();
   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 requireDeveloper();
+  const { session, response } = await requireByok();
   if (response) return response;
 
   const limited = await applyRateLimit(`rl:ai-keys:${session!.user.id}`, 5, 3600);

apps/web/app/api/v1/users/me/developer-access/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { db, users, eq } from "@epicure/db";
+import { requireSession } from "@/lib/api-auth";
+import { canSelfServeDeveloperAccess } from "@/lib/permissions";
+
+const PatchSchema = z.object({ enabled: z.boolean() });
+
+/** Self-serve on/off for the same isDeveloper flag admin/users/[id] can
+ * also set — open to any paid tier, no added fee. Free tier still needs
+ * an admin grant (requireAdmin's path, unchanged). */
+export async function PATCH(req: NextRequest) {
+  const { session, response } = await requireSession();
+  if (response) return response;
+
+  const parsed = PatchSchema.safeParse(await req.json());
+  if (!parsed.success) {
+    return NextResponse.json({ error: "Validation error", issues: parsed.error.issues }, { status: 400 });
+  }
+
+  // Turning it off is always allowed, regardless of tier or who granted
+  // it — only turning it ON self-serve requires a paid tier.
+  if (parsed.data.enabled) {
+    // Don't trust session.user.tier — up to 5-minute-stale cookieCache,
+    // same reasoning as every other fresh-role/tier re-query in this codebase.
+    const [dbUser] = await db.select({ tier: users.tier }).from(users).where(eq(users.id, session!.user.id)).limit(1);
+    if (!dbUser || !canSelfServeDeveloperAccess(dbUser)) {
+      return NextResponse.json({ error: "Upgrade to a paid plan to enable developer access yourself, or ask an admin" }, { status: 403 });
+    }
+  }
+
+  await db.update(users).set({ isDeveloper: parsed.data.enabled, updatedAt: new Date() }).where(eq(users.id, session!.user.id));
+
+  return NextResponse.json({ ok: true, isDeveloper: parsed.data.enabled });
+}