Tighten API key authorization

Author: SirEdvin

README.md

@@ -333,6 +333,7 @@ Personal API keys for automation clients:
 - Create and manage keys from the authenticated account API: `GET /auth/api-keys`, `POST /auth/api-keys`, and `DELETE /auth/api-keys/:id`.
 - `POST /auth/api-keys` accepts `{ "name": "Obsidian" }` and returns the plaintext token once. Store it immediately; ExcaliDash stores only a hash and metadata.
 - Automation clients such as the Obsidian plugin should call normal drawing and collection APIs with `Authorization: Bearer <key>`, for example `Authorization: Bearer exd_...`.
+- API keys are scoped automation credentials for `/drawings` and `/collections` only. They cannot manage account settings, create/revoke API keys, call admin endpoints, or use import/export APIs.
 - API-key Bearer requests without browser `Origin`/`Referer` headers do not require CSRF tokens. Cookie-authenticated browser requests keep the existing CSRF behavior.
 
 </details>

backend/src/__tests__/api-key-auth.integration.ts

@@ -11,6 +11,7 @@ describe("API key authentication", () => {
   let userId: string;
   let apiKeyId: string;
   let apiKeyToken: string;
+  let adminApiKeyToken: string;
 
   beforeAll(async () => {
     setupTestDb();
@@ -50,6 +51,29 @@ describe("API key authentication", () => {
       select: { id: true },
     });
     apiKeyId = apiKey.id;
+
+    const adminUser = await prisma.user.create({
+      data: {
+        email: "api-key-admin@test.local",
+        passwordHash,
+        name: "API Key Admin",
+        role: "ADMIN",
+        isActive: true,
+      },
+      select: { id: true },
+    });
+    const adminGenerated = generateApiKey();
+    adminApiKeyToken = adminGenerated.token;
+    await prisma.apiKey.create({
+      data: {
+        userId: adminUser.id,
+        name: "Admin automation",
+        keyId: adminGenerated.keyId,
+        tokenHash: adminGenerated.tokenHash,
+        prefix: adminGenerated.prefix,
+        scopes: serializeApiKeyScopes(),
+      },
+    });
   });
 
   afterAll(async () => {
@@ -70,6 +94,35 @@ describe("API key authentication", () => {
     expect(stored?.lastUsedAt).toBeInstanceOf(Date);
   });
 
+  it("accepts API key bearer auth for allowed read routes", async () => {
+    const collectionsResponse = await request(app)
+      .get("/collections")
+      .set("Authorization", `Bearer ${apiKeyToken}`);
+    const drawingsResponse = await request(app)
+      .get("/drawings")
+      .set("Authorization", `Bearer ${apiKeyToken}`);
+
+    expect(collectionsResponse.status).toBe(200);
+    expect(drawingsResponse.status).toBe(200);
+  });
+
+  it("rejects API key management with API key auth", async () => {
+    const response = await request(app)
+      .get("/auth/api-keys")
+      .set("Authorization", `Bearer ${apiKeyToken}`);
+
+    expect(response.status).toBe(403);
+  });
+
+  it("rejects admin actions with admin-owned API key auth", async () => {
+    const response = await request(app)
+      .get("/auth/users")
+      .set("Authorization", `Bearer ${adminApiKeyToken}`)
+      .send();
+
+    expect(response.status).toBe(403);
+  });
+
   it("stores only hashed API keys and metadata", async () => {
     const stored = await prisma.apiKey.findUnique({ where: { id: apiKeyId } });
 

backend/src/auth/apiKeys.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { API_KEY_PREFIX, extractApiKeyId } from "./apiKeys";
+
+describe("API key helpers", () => {
+  it("extracts generated-format key IDs that contain underscores", () => {
+    const keyId = "abcd_efgh_123456";
+    const token = `${API_KEY_PREFIX}${keyId}_secret_value`;
+
+    expect(extractApiKeyId(token)).toBe(keyId);
+  });
+});

backend/src/auth/apiKeys.ts

@@ -34,7 +34,7 @@ export const isApiKeyToken = (token: string): boolean => token.startsWith(API_KE
 export const extractApiKeyId = (token: string): string | null => {
   if (!isApiKeyToken(token)) return null;
   const withoutPrefix = token.slice(API_KEY_PREFIX.length);
-  const separatorIndex = withoutPrefix.indexOf("_");
+  const separatorIndex = withoutPrefix[16] === "_" ? 16 : withoutPrefix.indexOf("_");
   if (separatorIndex <= 0) return null;
   const keyId = withoutPrefix.slice(0, separatorIndex);
   return /^[A-Za-z0-9_-]{8,64}$/.test(keyId) ? keyId : null;

backend/src/middleware/auth.test.ts

@@ -4,7 +4,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { config } from "../config";
 import { createAuthMiddleware } from "./auth";
 import { BOOTSTRAP_USER_ID } from "../auth/authMode";
-import { generateApiKey } from "../auth/apiKeys";
+import { generateApiKey, serializeApiKeyScopes } from "../auth/apiKeys";
 
 const createRequest = (overrides?: Partial<Request>): Request =>
   ({
@@ -203,6 +203,7 @@ describe("auth middleware", () => {
     prisma.apiKey.findUnique.mockResolvedValue({
       id: "api-key-1",
       tokenHash: generated.tokenHash,
+      scopes: serializeApiKeyScopes(),
       revokedAt: null,
       user: {
         id: "user-1",
@@ -240,6 +241,122 @@ describe("auth middleware", () => {
     });
   });
 
+  it("allows valid API key auth when lastUsedAt update fails", async () => {
+    const { prisma, authModeService } = createDeps();
+    authModeService.getAuthEnabled.mockResolvedValue(true);
+    const generated = generateApiKey();
+    prisma.apiKey.findUnique.mockResolvedValue({
+      id: "api-key-1",
+      tokenHash: generated.tokenHash,
+      scopes: serializeApiKeyScopes(),
+      revokedAt: null,
+      user: {
+        id: "user-1",
+        username: "user1",
+        email: "user-1@test.local",
+        name: "User One",
+        role: "USER",
+        mustResetPassword: false,
+        isActive: true,
+      },
+    });
+    prisma.apiKey.update.mockRejectedValue(new Error("write failed"));
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const { requireAuth } = createAuthMiddleware({ prisma, authModeService });
+
+    const req = createRequest({
+      method: "GET",
+      originalUrl: "/drawings",
+      headers: {
+        authorization: `Bearer ${generated.token}`,
+      },
+    });
+    const res = createResponse();
+    const next = vi.fn() as NextFunction;
+
+    await requireAuth(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(res.status).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("rejects API keys for routes outside drawings and collections", async () => {
+    const { prisma, authModeService } = createDeps();
+    authModeService.getAuthEnabled.mockResolvedValue(true);
+    const generated = generateApiKey();
+    prisma.apiKey.findUnique.mockResolvedValue({
+      id: "api-key-1",
+      tokenHash: generated.tokenHash,
+      scopes: serializeApiKeyScopes(),
+      revokedAt: null,
+      user: {
+        id: "admin-1",
+        username: "admin",
+        email: "admin@test.local",
+        name: "Admin",
+        role: "ADMIN",
+        mustResetPassword: false,
+        isActive: true,
+      },
+    });
+    prisma.apiKey.update.mockResolvedValue({});
+    const { requireAuth } = createAuthMiddleware({ prisma, authModeService });
+
+    const req = createRequest({
+      method: "GET",
+      originalUrl: "/auth/api-keys",
+      headers: {
+        authorization: `Bearer ${generated.token}`,
+      },
+    });
+    const res = createResponse();
+    const next = vi.fn() as NextFunction;
+
+    await requireAuth(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("rejects API keys missing the required resource scope", async () => {
+    const { prisma, authModeService } = createDeps();
+    authModeService.getAuthEnabled.mockResolvedValue(true);
+    const generated = generateApiKey();
+    prisma.apiKey.findUnique.mockResolvedValue({
+      id: "api-key-1",
+      tokenHash: generated.tokenHash,
+      scopes: serializeApiKeyScopes(["drawings:read"]),
+      revokedAt: null,
+      user: {
+        id: "user-1",
+        username: "user1",
+        email: "user-1@test.local",
+        name: "User One",
+        role: "USER",
+        mustResetPassword: false,
+        isActive: true,
+      },
+    });
+    prisma.apiKey.update.mockResolvedValue({});
+    const { requireAuth } = createAuthMiddleware({ prisma, authModeService });
+
+    const req = createRequest({
+      method: "POST",
+      originalUrl: "/drawings",
+      headers: {
+        authorization: `Bearer ${generated.token}`,
+      },
+    });
+    const res = createResponse();
+    const next = vi.fn() as NextFunction;
+
+    await requireAuth(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
   it("rejects revoked API keys", async () => {
     const { prisma, authModeService } = createDeps();
     authModeService.getAuthEnabled.mockResolvedValue(true);

backend/src/middleware/auth.ts

@@ -13,6 +13,7 @@ import {
   apiKeyHashMatches,
   extractApiKeyId,
   isApiKeyToken,
+  parseApiKeyScopes,
 } from "../auth/apiKeys";
 
 declare global {
@@ -123,6 +124,36 @@ const isAllowedWhileMustResetPassword = (req: Request): boolean => {
   return false;
 };
 
+const getRequiredApiKeyScope = (req: Request): string | null => {
+  const path = normalizeRequestPath(req);
+  const resource = path === "/drawings" || path.startsWith("/drawings/")
+    ? "drawings"
+    : path === "/collections" || path.startsWith("/collections/")
+      ? "collections"
+      : null;
+  if (!resource) return null;
+
+  const access = req.method === "GET" || req.method === "HEAD" ? "read" : "write";
+  return `${resource}:${access}`;
+};
+
+const authorizeApiKeyRequest = (
+  req: Request,
+  res: Response,
+  scopes: string[],
+): boolean => {
+  const requiredScope = getRequiredApiKeyScope(req);
+  if (requiredScope && scopes.includes(requiredScope)) {
+    return true;
+  }
+
+  res.status(403).json({
+    error: "Forbidden",
+    message: "API key is not authorized for this route",
+  });
+  return false;
+};
+
 export type AuthMiddlewareDeps = {
   prisma: PrismaClient;
   authModeService: AuthModeService;
@@ -169,12 +200,16 @@ export const createAuthMiddleware = ({
     if (!apiKeyHashMatches(token, apiKey.tokenHash)) return null;
     if (!apiKey.user.isActive) return null;
 
-    await prisma.apiKey.update({
-      where: { id: apiKey.id },
-      data: { lastUsedAt: new Date() },
-    });
+    try {
+      await prisma.apiKey.update({
+        where: { id: apiKey.id },
+        data: { lastUsedAt: new Date() },
+      });
+    } catch (error) {
+      console.warn("Failed to update API key lastUsedAt:", error);
+    }
 
-    return apiKey.user;
+    return { user: apiKey.user, scopes: parseApiKeyScopes(apiKey.scopes) };
   };
 
   const shouldReconcileOidcRole = async (
@@ -283,14 +318,19 @@ export const createAuthMiddleware = ({
 
     if (extracted.source === "bearer" && isApiKeyToken(extracted.token)) {
       try {
-        const user = await authenticateApiKey(extracted.token);
-        if (!user) {
+        const result = await authenticateApiKey(extracted.token);
+        if (!result) {
           res.status(401).json({
             error: "Unauthorized",
             message: "Invalid or revoked API key",
           });
           return;
         }
+        const { user, scopes } = result;
+
+        if (!authorizeApiKeyRequest(req, res, scopes)) {
+          return;
+        }
 
         if (user.mustResetPassword && !isAllowedWhileMustResetPassword(req)) {
           res.status(403).json({
@@ -419,8 +459,12 @@ export const createAuthMiddleware = ({
 
     if (extracted.source === "bearer" && isApiKeyToken(extracted.token)) {
       try {
-        const user = await authenticateApiKey(extracted.token);
-        if (user) {
+        const result = await authenticateApiKey(extracted.token);
+        if (result) {
+          if (!authorizeApiKeyRequest(req, res, result.scopes)) {
+            return;
+          }
+          const { user } = result;
           req.user = {
             id: user.id,
             username: user.username,