Replace entire codebase with homarr-labs/homarr

packages/auth/api-key/constants.ts

@@ -0,0 +1 @@
+export const API_KEY_HEADER_NAME = "ApiKey";

packages/auth/api-key/get-api-key-session.ts

@@ -0,0 +1,76 @@
+import type { Session } from "next-auth";
+
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import type { Database } from "@homarr/db";
+import { eq } from "@homarr/db";
+import { apiKeys } from "@homarr/db/schema";
+
+import { hashPasswordAsync } from "../security";
+import { createSessionAsync } from "../server";
+
+const logger = createLogger({ module: "apiKeyAuth" });
+
+/**
+ * Validate an API key from the request header and return a session if valid.
+ *
+ * @param db - The database instance
+ * @param apiKeyHeaderValue - The value of the ApiKey header (format: "id.token")
+ * @param ipAddress - The IP address of the request (for logging)
+ * @param userAgent - The user agent of the request (for logging)
+ * @returns A session if the API key is valid, null otherwise
+ */
+export const getSessionFromApiKeyAsync = async (
+  db: Database,
+  apiKeyHeaderValue: string | null,
+  ipAddress: string | null,
+  userAgent: string,
+): Promise<Session | null> => {
+  if (apiKeyHeaderValue === null) {
+    return null;
+  }
+
+  const [apiKeyId, apiKey] = apiKeyHeaderValue.split(".");
+
+  if (!apiKeyId || !apiKey) {
+    logger.warn("Failed to authenticate with api-key", { ipAddress, userAgent, reason: "API_KEY_INVALID_FORMAT" });
+    return null;
+  }
+
+  const apiKeyFromDb = await db.query.apiKeys.findFirst({
+    where: eq(apiKeys.id, apiKeyId),
+    columns: {
+      id: true,
+      apiKey: true,
+      salt: true,
+    },
+    with: {
+      user: {
+        columns: {
+          id: true,
+          name: true,
+          email: true,
+          emailVerified: true,
+        },
+      },
+    },
+  });
+
+  if (!apiKeyFromDb) {
+    logger.warn("Failed to authenticate with api-key", { ipAddress, userAgent, reason: "API_KEY_NOT_FOUND" });
+    return null;
+  }
+
+  const hashedApiKey = await hashPasswordAsync(apiKey, apiKeyFromDb.salt);
+
+  if (apiKeyFromDb.apiKey !== hashedApiKey) {
+    logger.warn("Failed to authenticate with api-key", { ipAddress, userAgent, reason: "API_KEY_MISMATCH" });
+    return null;
+  }
+
+  logger.info("Successfully authenticated with api-key", {
+    name: apiKeyFromDb.user.name,
+    id: apiKeyFromDb.user.id,
+  });
+
+  return await createSessionAsync(db, apiKeyFromDb.user);
+};

packages/auth/api-key/index.ts

@@ -0,0 +1,2 @@
+export { getSessionFromApiKeyAsync } from "./get-api-key-session";
+export { API_KEY_HEADER_NAME } from "./constants";

packages/auth/api-key/test/get-api-key-session.spec.ts

@@ -0,0 +1,133 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { describe, expect, test, vi } from "vitest";
+
+import { createId } from "@homarr/common";
+import { apiKeys, users } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+
+import { createSaltAsync, hashPasswordAsync } from "../../security";
+import { getSessionFromApiKeyAsync } from "../get-api-key-session";
+
+// Mock the logger to avoid console output during tests
+vi.mock("@homarr/core/infrastructure/logs", () => ({
+  createLogger: () => ({
+    warn: vi.fn(),
+    info: vi.fn(),
+  }),
+}));
+
+const defaultUserId = createId();
+const defaultUsername = "testuser";
+const defaultApiKeyId = createId();
+const defaultIpAddress = "127.0.0.1";
+const defaultUserAgent = "test-agent";
+const defaultLogParams = [defaultIpAddress, defaultUserAgent] as const;
+
+describe("getSessionFromApiKeyAsync", () => {
+  test("should return null when api key header is null", async () => {
+    // Arrange
+    const { db } = await setupAsync();
+    const apiKey = null;
+
+    // Act
+    const result = await getSessionFromApiKeyAsync(db, apiKey, ...defaultLogParams);
+
+    // Assert
+    expect(result).toBeNull();
+  });
+
+  test.each([
+    ["invalidformat", "no dot"],
+    ["keyid.", "missing token"],
+    [".token", "missing id"],
+  ])("should return null when api key format is invalid key=%s reason=%s", async (apiKey) => {
+    // Arrange
+    const { db } = await setupAsync();
+
+    // Act
+    const result = await getSessionFromApiKeyAsync(db, apiKey, ...defaultLogParams);
+
+    // Assert
+    expect(result).toBeNull();
+  });
+
+  test("should return null when api key is not found in database", async () => {
+    // Arrange
+    const { db } = await setupAsync();
+
+    // Act
+    const result = await getSessionFromApiKeyAsync(db, "nonexistent.token", ...defaultLogParams);
+
+    // Assert
+    expect(result).toBeNull();
+  });
+
+  test("should return null when api key token does not match", async () => {
+    // Arrange
+    const { db } = await setupAsync({ token: "correcttoken" });
+
+    // Act
+    const result = await getSessionFromApiKeyAsync(db, `${defaultApiKeyId}.wrongtoken`, ...defaultLogParams);
+
+    // Assert
+    expect(result).toBeNull();
+  });
+
+  test("should return session when api key is valid", async () => {
+    // Arrange
+    const token = "validtesttoken123";
+    const { db } = await setupAsync({ token });
+
+    // Act
+    const result = await getSessionFromApiKeyAsync(db, `${defaultApiKeyId}.${token}`, ...defaultLogParams);
+
+    // Assert
+    expect(result).not.toBeNull();
+    expect(result!.user.id).toEqual(defaultUserId);
+    expect(result!.user.name).toEqual(defaultUsername);
+  });
+
+  test("should work with null ip address", async () => {
+    // Arrange
+    const token = "validtesttoken456";
+    const { db } = await setupAsync({ token });
+
+    // Act
+    const result = await getSessionFromApiKeyAsync(db, `${defaultApiKeyId}.${token}`, null, defaultUserAgent);
+
+    // Assert
+    expect(result).not.toBeNull();
+    expect(result!.user.id).toEqual(defaultUserId);
+  });
+});
+
+interface SetupOptions {
+  /**
+   * If provided, inserts an API key into the database for testing.
+   */
+  token?: string;
+}
+
+const setupAsync = async (options?: SetupOptions) => {
+  const db = createDb();
+
+  await db.insert(users).values({
+    id: defaultUserId,
+    name: defaultUsername,
+    email: "test@example.com",
+  });
+
+  if (options?.token) {
+    const salt = await createSaltAsync();
+    await db.insert(apiKeys).values({
+      id: defaultApiKeyId,
+      apiKey: await hashPasswordAsync(options.token, salt),
+      salt,
+      userId: defaultUserId,
+    });
+  }
+
+  return {
+    db,
+  };
+};