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">
-                <p className="text-sm font-medium truncate">{k.name}</p>
+                <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);