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/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);