@hot-updater/server 0.36.7 → 1.0.0-rc.1

package/src/apiKeys.spec.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createInMemoryDatabasePlugin } from "../../test-utils/test/inMemoryDatabasePlugin";
+import {
+  API_KEY_HEADER_NAME,
+  authenticateApiKey,
+  createApiKey,
+  createApiKeyManagement,
+  hashApiKey,
+  normalizeApiKeyHeaderName,
+  provisionApiKey,
+  registerApiKey,
+} from "./apiKeys";
+
+const API_KEY = "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE";
+
+describe("API keys", () => {
+  it("normalizes valid header names and rejects invalid names", () => {
+    expect(normalizeApiKeyHeaderName()).toBe("x-api-key");
+    expect(normalizeApiKeyHeaderName("X-Hot-Updater-Key")).toBe(
+      "x-hot-updater-key",
+    );
+    expect(() => normalizeApiKeyHeaderName("")).toThrow(
+      "clientAccess.headerName must be a valid header name.",
+    );
+    expect(() => normalizeApiKeyHeaderName("invalid header")).toThrow(
+      "clientAccess.headerName must be a valid header name.",
+    );
+  });
+
+  it("persists only the digest and metadata for a registered key", async () => {
+    const database = createInMemoryDatabasePlugin();
+
+    const created = await registerApiKey({
+      apiKeys: database.models.apiKeys,
+      apiKey: API_KEY,
+      createdAtMs: 100,
+      name: " Production app ",
+    });
+
+    expect(created.apiKey).toBe(API_KEY);
+    expect(created.record).toEqual({
+      created_at_ms: 100,
+      id: expect.stringMatching(/^api-[A-Za-z0-9_-]{22}$/u),
+      name: "Production app",
+      prefix: "AQEBAQ",
+      revoked_at_ms: null,
+      role: "client",
+    });
+    expect(created.record).not.toHaveProperty("hash");
+    expect(created.record.id).not.toContain(await hashApiKey(API_KEY));
+    expect(await database.models.apiKeys.list()).toEqual([
+      expect.objectContaining({ hash: await hashApiKey(API_KEY) }),
+    ]);
+    expect(JSON.stringify(await database.models.apiKeys.list())).not.toContain(
+      API_KEY,
+    );
+
+    const registeredAgain = await registerApiKey({
+      apiKeys: database.models.apiKeys,
+      apiKey: API_KEY,
+      createdAtMs: 200,
+      name: "Ignored replacement name",
+    });
+    expect(registeredAgain.record).toEqual(created.record);
+    expect(await database.models.apiKeys.list()).toHaveLength(1);
+  });
+
+  it("authenticates only active keys after the readiness check", async () => {
+    const database = createInMemoryDatabasePlugin();
+    const beforeLookup = vi.fn(async () => undefined);
+    const { record } = await registerApiKey({
+      apiKeys: database.models.apiKeys,
+      apiKey: API_KEY,
+      name: "App",
+    });
+    const request = new Request("https://example.com", {
+      headers: { [API_KEY_HEADER_NAME]: API_KEY },
+    });
+
+    await expect(
+      authenticateApiKey({
+        apiKeys: database.models.apiKeys,
+        beforeLookup,
+        request,
+      }),
+    ).resolves.toBe(true);
+    expect(beforeLookup).toHaveBeenCalledOnce();
+
+    await database.models.apiKeys.revoke({
+      id: record.id,
+      revokedAtMs: Date.now(),
+    });
+    await expect(
+      authenticateApiKey({
+        apiKeys: database.models.apiKeys,
+        request,
+      }),
+    ).resolves.toBe(false);
+  });
+
+  it("creates a canonical key and validates visible names", async () => {
+    const database = createInMemoryDatabasePlugin();
+
+    const created = await createApiKey({
+      apiKeys: database.models.apiKeys,
+      name: "App",
+    });
+
+    expect(created.apiKey).toMatch(/^[A-Za-z0-9_-]{43}$/u);
+    expect(created.record.prefix).toBe(created.apiKey.slice(0, 6));
+    await expect(
+      registerApiKey({
+        apiKeys: database.models.apiKeys,
+        apiKey: API_KEY,
+        name: "   ",
+      }),
+    ).rejects.toThrow("1-64 visible characters");
+  });
+
+  it("provisions a new key once and reuses an existing managed key", async () => {
+    const database = createInMemoryDatabasePlugin();
+
+    const created = await provisionApiKey({
+      apiKeys: database.models.apiKeys,
+      name: "Managed init",
+    });
+    const reused = await provisionApiKey({
+      apiKeys: database.models.apiKeys,
+      existingApiKey: created.apiKey,
+      name: "Managed init rerun",
+    });
+
+    expect(reused).toEqual(created);
+    expect(await database.models.apiKeys.list()).toHaveLength(1);
+  });
+
+  it("manages keys without exposing stored hashes", async () => {
+    const database = createInMemoryDatabasePlugin();
+    const beforeOperation = vi.fn(async () => undefined);
+    const apiKeys = createApiKeyManagement({
+      apiKeys: database.models.apiKeys,
+      beforeOperation,
+    });
+
+    const created = await apiKeys.create({ name: "Production app" });
+    expect(created.apiKey).toMatch(/^[A-Za-z0-9_-]{43}$/u);
+    expect(created.record).not.toHaveProperty("hash");
+
+    const records = await apiKeys.list();
+    expect(records).toEqual([created.record]);
+    expect(records[0]).not.toHaveProperty("hash");
+
+    const revoked = await apiKeys.revoke({ id: created.record.id });
+    expect(revoked).toMatchObject({
+      id: created.record.id,
+      revoked_at_ms: expect.any(Number),
+    });
+    expect(revoked).not.toHaveProperty("hash");
+    expect(beforeOperation).toHaveBeenCalledTimes(3);
+  });
+});

package/src/apiKeys.ts

@@ -0,0 +1,220 @@
+import type { ApiKeyModel, ApiKeyRow } from "@hot-updater/plugin-core";
+
+export const API_KEY_HEADER_NAME = "x-api-key";
+
+const BASE64URL_32_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
+
+const bytesToBase64Url = (bytes: Uint8Array): string => {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/u, "");
+};
+
+export const isApiKey = (value: string): boolean => {
+  if (!BASE64URL_32_PATTERN.test(value)) return false;
+
+  try {
+    const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+    const binary = atob(`${base64}=`);
+    const bytes = Uint8Array.from(binary, (character) =>
+      character.charCodeAt(0),
+    );
+    return bytes.byteLength === 32 && bytesToBase64Url(bytes) === value;
+  } catch {
+    return false;
+  }
+};
+
+export const normalizeApiKeyHeaderName = (
+  value: unknown = API_KEY_HEADER_NAME,
+): string => {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("clientAccess.headerName must be a valid header name.");
+  }
+
+  try {
+    const headers = new Headers();
+    headers.set(value, "");
+    return headers.keys().next().value!;
+  } catch {
+    throw new TypeError("clientAccess.headerName must be a valid header name.");
+  }
+};
+
+export const hashApiKey = async (apiKey: string): Promise<string> => {
+  if (!isApiKey(apiKey)) {
+    throw new TypeError("API key must be a canonical 32-byte base64url value.");
+  }
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(apiKey),
+  );
+  return bytesToBase64Url(new Uint8Array(digest));
+};
+
+export const apiKeyId = (): string => {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return `api-${bytesToBase64Url(bytes)}`;
+};
+
+export const normalizeApiKeyName = (name: string): string => {
+  const normalized = name.trim();
+  if (
+    normalized.length === 0 ||
+    normalized.length > 64 ||
+    /[\p{Cc}\p{Cf}]/u.test(normalized)
+  ) {
+    throw new TypeError("API key names must contain 1-64 visible characters.");
+  }
+  return normalized;
+};
+
+export type ApiKeyMetadata = Omit<ApiKeyRow, "hash">;
+
+export interface CreatedApiKey {
+  /** Plaintext credential. It cannot be recovered after this call returns. */
+  readonly apiKey: string;
+  /** Non-secret metadata. The persisted SHA-256 hash is never exposed. */
+  readonly record: ApiKeyMetadata;
+}
+
+export interface ApiKeyManagementAPI {
+  /** Creates an API key and returns its plaintext exactly once. */
+  create(input: { readonly name: string }): Promise<{
+    readonly apiKey: string;
+    readonly record: ApiKeyMetadata;
+  }>;
+  /** Lists non-secret API key metadata, including revoked keys. */
+  list(): Promise<readonly ApiKeyMetadata[]>;
+  /** Revokes an API key immediately and returns only non-secret metadata. */
+  revoke(input: { readonly id: string }): Promise<ApiKeyMetadata | null>;
+}
+
+const toApiKeyMetadata = ({
+  hash: _hash,
+  ...metadata
+}: ApiKeyRow): ApiKeyMetadata => Object.freeze(metadata);
+
+export const registerApiKey = async (input: {
+  readonly apiKey: string;
+  readonly apiKeys: ApiKeyModel;
+  readonly createdAtMs?: number;
+  readonly name: string;
+}): Promise<CreatedApiKey> => {
+  const hash = await hashApiKey(input.apiKey);
+  const createdAtMs = input.createdAtMs ?? Date.now();
+  if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0) {
+    throw new TypeError("API key creation time must be non-negative.");
+  }
+  const record = Object.freeze({
+    created_at_ms: createdAtMs,
+    hash,
+    id: apiKeyId(),
+    name: normalizeApiKeyName(input.name),
+    prefix: input.apiKey.slice(0, 6),
+    revoked_at_ms: null,
+    role: "client" as const,
+  });
+  const status = await input.apiKeys.create(record);
+  if (status === "existing") {
+    const existing = await input.apiKeys.findByHash(hash);
+    if (existing === null || existing.revoked_at_ms !== null) {
+      throw new Error("The API key has been revoked.");
+    }
+    return Object.freeze({
+      apiKey: input.apiKey,
+      record: toApiKeyMetadata(existing),
+    });
+  }
+  return Object.freeze({
+    apiKey: input.apiKey,
+    record: toApiKeyMetadata(record),
+  });
+};
+
+export const createApiKey = (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly name: string;
+}): Promise<CreatedApiKey> => {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return registerApiKey({
+    apiKey: bytesToBase64Url(bytes),
+    apiKeys: input.apiKeys,
+    name: input.name,
+  });
+};
+
+/**
+ * Provisions the client API key used by managed init.
+ *
+ * A saved plaintext key is registered idempotently; otherwise a new key is
+ * created. Callers must persist or display the returned plaintext because the
+ * database stores only its hash.
+ */
+export const provisionApiKey = (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly existingApiKey?: string;
+  readonly name: string;
+}): Promise<CreatedApiKey> => {
+  const existingApiKey = input.existingApiKey?.trim();
+  return existingApiKey
+    ? registerApiKey({
+        apiKey: existingApiKey,
+        apiKeys: input.apiKeys,
+        name: input.name,
+      })
+    : createApiKey({ apiKeys: input.apiKeys, name: input.name });
+};
+
+export const authenticateApiKey = async (input: {
+  readonly beforeLookup?: () => Promise<void>;
+  readonly apiKeys: ApiKeyModel;
+  readonly headerName?: string;
+  readonly request: Request;
+}): Promise<boolean> => {
+  const apiKey = input.request.headers.get(
+    normalizeApiKeyHeaderName(input.headerName),
+  );
+  if (apiKey === null || !isApiKey(apiKey)) return false;
+  const hash = await hashApiKey(apiKey);
+  await input.beforeLookup?.();
+  const record = await input.apiKeys.findByHash(hash);
+  return (
+    record !== null &&
+    record.hash === hash &&
+    record.role === "client" &&
+    record.revoked_at_ms === null
+  );
+};
+
+export const createApiKeyManagement = (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly beforeOperation: () => Promise<void>;
+}): ApiKeyManagementAPI =>
+  Object.freeze({
+    async create({ name }: { readonly name: string }) {
+      await input.beforeOperation();
+      const created = await createApiKey({ apiKeys: input.apiKeys, name });
+      return Object.freeze({
+        apiKey: created.apiKey,
+        record: created.record,
+      });
+    },
+    async list() {
+      await input.beforeOperation();
+      return Object.freeze((await input.apiKeys.list()).map(toApiKeyMetadata));
+    },
+    async revoke({ id }: { readonly id: string }) {
+      await input.beforeOperation();
+      const record = await input.apiKeys.revoke({
+        id,
+        revokedAtMs: Date.now(),
+      });
+      return record === null ? null : toApiKeyMetadata(record);
+    },
+  });