feat: read-only API key scoping

New keys can be created as "Full access" (default, unchanged) or
"Read-only" — read-only keys can only make GET/HEAD/OPTIONS requests,
enforced once in requireSessionOrApiKey (lib/api-auth.ts) rather than in
every route, since a route has no way to know a request came from a
scoped key without that check. Existing keys default to full access —
no behavior change for anyone who doesn't opt in.

Also included in this migration: the chat_messages table for the
next commit (chat history persistence) — generated together since both
touched packages/db/src/schema/users.ts in the same pass.

Verified locally: created both a read-only and a full-access key,
confirmed GET succeeds and POST 403s on the read-only key, confirmed
POST still works on the full-access key, and checked the scope badges
render correctly in the real Settings → API Keys UI.

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

@@ -18,6 +18,7 @@ export default async function ApiKeysPage() {
     .select({
       id: apiKeys.id,
       name: apiKeys.name,
+      scope: apiKeys.scope,
       lastUsedAt: apiKeys.lastUsedAt,
       createdAt: apiKeys.createdAt,
     })
@@ -45,6 +46,7 @@ export default async function ApiKeysPage() {
           initialKeys={keys.map((k) => ({
             id: k.id,
             name: k.name,
+            scope: k.scope,
             lastUsedAt: k.lastUsedAt ? k.lastUsedAt.toISOString() : null,
             createdAt: k.createdAt.toISOString(),
           }))}

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

@@ -6,6 +6,7 @@ import { requireSession } from "@/lib/api-auth";
 
 const CreateApiKeyBody = z.object({
   name: z.string().min(1).max(100),
+  scope: z.enum(["full", "read"]).default("full"),
 });
 
 export async function GET() {
@@ -16,6 +17,7 @@ export async function GET() {
     .select({
       id: apiKeys.id,
       name: apiKeys.name,
+      scope: apiKeys.scope,
       lastUsedAt: apiKeys.lastUsedAt,
       createdAt: apiKeys.createdAt,
     })
@@ -56,11 +58,12 @@ export async function POST(req: NextRequest) {
     userId: session!.user.id,
     name: parsed.data.name,
     keyHash,
+    scope: parsed.data.scope,
     createdAt: now,
   });
 
   return NextResponse.json(
-    { id, name: parsed.data.name, key: rawKey, createdAt: now.toISOString() },
+    { id, name: parsed.data.name, scope: parsed.data.scope, key: rawKey, createdAt: now.toISOString() },
     { status: 201 }
   );
 }

apps/web/components/settings/api-keys-manager.tsx

@@ -7,10 +7,14 @@ import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Badge } from "@/components/ui/badge";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+
+type ApiKeyScope = "full" | "read";
 
 type ApiKey = {
   id: string;
   name: string;
+  scope: ApiKeyScope;
   lastUsedAt: string | null;
   createdAt: string;
 };
@@ -18,6 +22,7 @@ type ApiKey = {
 type CreateApiKeyResponse = {
   id: string;
   name: string;
+  scope: ApiKeyScope;
   key: string;
   createdAt: string;
 };
@@ -34,6 +39,7 @@ export function ApiKeysManager({ initialKeys }: { initialKeys: ApiKey[] }) {
   const t = useTranslations("settingsForm");
   const [keys, setKeys] = useState<ApiKey[]>(initialKeys);
   const [name, setName] = useState("");
+  const [scope, setScope] = useState<ApiKeyScope>("full");
   const [creating, setCreating] = useState(false);
   const [newKey, setNewKey] = useState<string | null>(null);
   const [copied, setCopied] = useState(false);
@@ -46,7 +52,7 @@ export function ApiKeysManager({ initialKeys }: { initialKeys: ApiKey[] }) {
       const res = await fetch("/api/v1/api-keys", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name: name.trim() }),
+        body: JSON.stringify({ name: name.trim(), scope }),
       });
       if (!res.ok) {
         const data = await res.json() as { error?: string };
@@ -55,10 +61,11 @@ export function ApiKeysManager({ initialKeys }: { initialKeys: ApiKey[] }) {
       const data = await res.json() as CreateApiKeyResponse;
       setNewKey(data.key);
       setKeys((prev) => [
-        { id: data.id, name: data.name, lastUsedAt: null, createdAt: data.createdAt },
+        { id: data.id, name: data.name, scope: data.scope, lastUsedAt: null, createdAt: data.createdAt },
         ...prev,
       ]);
       setName("");
+      setScope("full");
     } catch (err) {
       toast.error(err instanceof Error ? err.message : t("apiKeyCreateFailed"));
     } finally {
@@ -105,10 +112,20 @@ export function ApiKeysManager({ initialKeys }: { initialKeys: ApiKey[] }) {
               maxLength={100}
               required
             />
+            <Select value={scope} onValueChange={(v) => setScope(v as ApiKeyScope)}>
+              <SelectTrigger className="w-36">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="full">{t("apiKeyScopeFull")}</SelectItem>
+                <SelectItem value="read">{t("apiKeyScopeRead")}</SelectItem>
+              </SelectContent>
+            </Select>
             <Button type="submit" disabled={creating || !name.trim()}>
               {creating ? t("apiKeyCreating") : t("apiKeyCreate")}
             </Button>
           </div>
+          <p className="text-xs text-muted-foreground">{t("apiKeyScopeHelp")}</p>
         </div>
       </form>
 
@@ -146,7 +163,12 @@ export function ApiKeysManager({ initialKeys }: { initialKeys: ApiKey[] }) {
           {keys.map((k) => (
             <div key={k.id} className="flex items-center justify-between px-4 py-3 gap-4">
               <div className="min-w-0 flex-1 space-y-1">
+                <div className="flex items-center gap-2">
                   <p className="text-sm font-medium truncate">{k.name}</p>
+                  <Badge variant={k.scope === "read" ? "secondary" : "default"} className="text-xs">
+                    {k.scope === "read" ? t("apiKeyScopeRead") : t("apiKeyScopeFull")}
+                  </Badge>
+                </div>
                 <div className="flex items-center gap-2 text-xs text-muted-foreground">
                   <span>{t("createdOn", { date: formatDate(k.createdAt) })}</span>
                   <span>·</span>

apps/web/lib/api-auth.ts

@@ -57,12 +57,22 @@ export async function requireSessionOrApiKey(
       const keyHash = crypto.createHash("sha256").update(rawKey).digest("hex");
 
       const [keyRow] = await db
-        .select({ id: apiKeys.id, userId: apiKeys.userId })
+        .select({ id: apiKeys.id, userId: apiKeys.userId, scope: apiKeys.scope })
         .from(apiKeys)
         .where(eq(apiKeys.keyHash, keyHash))
         .limit(1);
 
       if (keyRow) {
+        // Read-scoped keys can't make any state-changing request — enforced
+        // once here rather than in every route, since a route can't tell
+        // whether it's being called by a "read" key without this check.
+        if (keyRow.scope === "read" && !["GET", "HEAD", "OPTIONS"].includes(req.method)) {
+          return {
+            session: null,
+            response: NextResponse.json({ error: "This API key is read-only" }, { status: 403 }),
+          };
+        }
+
         // Update lastUsedAt asynchronously — don't block response
         void db
           .update(apiKeys)

apps/web/lib/openapi.ts

@@ -86,11 +86,11 @@ export function generateOpenApiSpec(): object {
   }));
 
   const ApiKeyRef = registry.register("ApiKey", z.object({
-    id: z.string(), name: z.string(), lastUsedAt: z.string().datetime().nullable(), createdAt: z.string().datetime(),
+    id: z.string(), name: z.string(), scope: z.enum(["full", "read"]), lastUsedAt: z.string().datetime().nullable(), createdAt: z.string().datetime(),
   }));
 
   const CreateApiKeyResponseRef = registry.register("CreateApiKeyResponse", z.object({
-    id: z.string(), name: z.string(), key: z.string().describe("Full key — shown once"), createdAt: z.string().datetime(),
+    id: z.string(), name: z.string(), scope: z.enum(["full", "read"]), key: z.string().describe("Full key — shown once"), createdAt: z.string().datetime(),
   }));
 
   const AiGeneratedRef = registry.register("AiGeneratedRecipe", z.object({
@@ -137,7 +137,7 @@ export function generateOpenApiSpec(): object {
   registry.registerPath({ method: "get", path: "/api/v1/shopping-lists", summary: "List shopping lists", security, request: { query: Pagination }, responses: { 200: { description: "Lists", content: { "application/json": { schema: z.array(ShoppingListRef) } } }, 401: { description: "Unauthorized", content: { "application/json": { schema: ApiErrorRef } } } } });
   registry.registerPath({ method: "post", path: "/api/v1/shopping-lists", summary: "Create shopping list", security, request: { body: { content: { "application/json": { schema: z.object({ name: z.string().min(1), fromMealPlanWeek: z.string().optional() }) } }, required: true } }, responses: { 201: { description: "Created", content: { "application/json": { schema: ShoppingListRef } } }, 401: { description: "Unauthorized", content: { "application/json": { schema: ApiErrorRef } } } } });
   registry.registerPath({ method: "get", path: "/api/v1/api-keys", summary: "List API keys", security, responses: { 200: { description: "Keys (hash never returned)", content: { "application/json": { schema: z.array(ApiKeyRef) } } }, 401: { description: "Unauthorized", content: { "application/json": { schema: ApiErrorRef } } } } });
-  registry.registerPath({ method: "post", path: "/api/v1/api-keys", summary: "Create API key", security, request: { body: { content: { "application/json": { schema: z.object({ name: z.string().min(1).max(100) }) } }, required: true } }, responses: { 201: { description: "Key created — shown once", content: { "application/json": { schema: CreateApiKeyResponseRef } } }, 401: { description: "Unauthorized", content: { "application/json": { schema: ApiErrorRef } } } } });
+  registry.registerPath({ method: "post", path: "/api/v1/api-keys", summary: "Create API key", security, request: { body: { content: { "application/json": { schema: z.object({ name: z.string().min(1).max(100), scope: z.enum(["full", "read"]).default("full").describe("read-only keys can only make GET requests") }) } }, required: true } }, responses: { 201: { description: "Key created — shown once", content: { "application/json": { schema: CreateApiKeyResponseRef } } }, 401: { description: "Unauthorized", content: { "application/json": { schema: ApiErrorRef } } } } });
   registry.registerPath({ method: "delete", path: "/api/v1/api-keys/{id}", summary: "Revoke API key", security, request: { params: idParam }, responses: { 204: { description: "Revoked" }, 401: { description: "Unauthorized", content: { "application/json": { schema: ApiErrorRef } } }, 404: { description: "Not found", content: { "application/json": { schema: ApiErrorRef } } } } });
 
   const generator = new OpenApiGeneratorV31(registry.definitions);

packages/db/src/migrations/0035_gifted_plazm.sql

@@ -0,0 +1,16 @@
+CREATE TYPE "public"."api_key_scope" AS ENUM('full', 'read');--> statement-breakpoint
+CREATE TYPE "public"."chat_role" AS ENUM('user', 'assistant');--> statement-breakpoint
+CREATE TABLE "chat_messages" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"recipe_id" text,
+	"role" "chat_role" NOT NULL,
+	"content" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "api_keys" ADD COLUMN "scope" "api_key_scope" DEFAULT 'full' NOT NULL;--> statement-breakpoint
+ALTER TABLE "chat_messages" ADD CONSTRAINT "chat_messages_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "chat_messages" ADD CONSTRAINT "chat_messages_recipe_id_recipes_id_fk" FOREIGN KEY ("recipe_id") REFERENCES "public"."recipes"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "chat_messages_user_idx" ON "chat_messages" USING btree ("user_id","created_at");--> statement-breakpoint
+CREATE INDEX "chat_messages_recipe_idx" ON "chat_messages" USING btree ("recipe_id");

packages/db/src/migrations/meta/_journal.json

@@ -246,6 +246,13 @@
       "when": 1783875228288,
       "tag": "0034_dapper_nocturne",
       "breakpoints": true
+    },
+    {
+      "idx": 35,
+      "version": "7",
+      "when": 1783887815564,
+      "tag": "0035_gifted_plazm",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/ai-chat.ts

@@ -0,0 +1,26 @@
+import { pgTable, text, timestamp, pgEnum, index } from "drizzle-orm/pg-core";
+import { relations } from "drizzle-orm";
+import { users } from "./users";
+import { recipes } from "./recipes";
+
+export const chatRoleEnum = pgEnum("chat_role", ["user", "assistant"]);
+
+// Persists both the per-recipe chat (recipeId set) and the general cooking
+// assistant on the recipes homepage (recipeId null) — same table, since a
+// user searching "their chat history" expects both to show up together.
+export const chatMessages = pgTable("chat_messages", {
+  id: text("id").primaryKey(),
+  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  recipeId: text("recipe_id").references(() => recipes.id, { onDelete: "cascade" }),
+  role: chatRoleEnum("role").notNull(),
+  content: text("content").notNull(),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (t) => [
+  index("chat_messages_user_idx").on(t.userId, t.createdAt),
+  index("chat_messages_recipe_idx").on(t.recipeId),
+]);
+
+export const chatMessagesRelations = relations(chatMessages, ({ one }) => ({
+  user: one(users, { fields: [chatMessages.userId], references: [users.id] }),
+  recipe: one(recipes, { fields: [chatMessages.recipeId], references: [recipes.id] }),
+}));

packages/db/src/schema/index.ts

@@ -6,3 +6,4 @@ export * from "./tiers";
 export * from "./webhooks";
 export * from "./messaging";
 export * from "./billing";
+export * from "./ai-chat";

packages/db/src/schema/users.ts

@@ -12,6 +12,7 @@ import { relations } from "drizzle-orm";
 export const userRoleEnum = pgEnum("user_role", ["user", "moderator", "admin"]);
 export const tierEnum = pgEnum("tier", ["free", "pro"]);
 export const unitPrefEnum = pgEnum("unit_pref", ["metric", "imperial"]);
+export const apiKeyScopeEnum = pgEnum("api_key_scope", ["full", "read"]);
 
 export const users = pgTable("users", {
   id: text("id").primaryKey(),
@@ -96,6 +97,7 @@ export const apiKeys = pgTable("api_keys", {
   userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
   name: text("name").notNull(),
   keyHash: text("key_hash").notNull().unique(),
+  scope: apiKeyScopeEnum("scope").notNull().default("full"),
   lastUsedAt: timestamp("last_used_at"),
   createdAt: timestamp("created_at").notNull().defaultNow(),
 });