@hot-updater/server 1.0.0-rc.2 → 1.0.0-rc.21

package/src/apiKeys.spec.ts

@@ -1,162 +0,0 @@
-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

@@ -1,220 +0,0 @@
-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);
-    },
-  });

package/src/calculatePagination.ts

@@ -1,34 +0,0 @@
-import type { PaginationInfo, PaginationOptions } from "./types";
-
-/**
- * Calculate pagination information based on total count, limit, and offset
- */
-export function calculatePagination(
-  total: number,
-  options: PaginationOptions,
-): PaginationInfo {
-  const { limit, offset } = options;
-
-  if (total === 0) {
-    return {
-      total: 0,
-      hasNextPage: false,
-      hasPreviousPage: false,
-      currentPage: 1,
-      totalPages: 0,
-    };
-  }
-
-  const currentPage = Math.floor(offset / limit) + 1;
-  const totalPages = Math.ceil(total / limit);
-  const hasNextPage = offset + limit < total;
-  const hasPreviousPage = offset > 0;
-
-  return {
-    total,
-    hasNextPage,
-    hasPreviousPage,
-    currentPage,
-    totalPages,
-  };
-}

package/src/createHotUpdaterCore.ts

@@ -1,246 +0,0 @@
-import {
-  assertStorageOperations,
-  type InsightsModel,
-  type StoragePlugin,
-} from "@hot-updater/plugin-core";
-
-import {
-  authenticateApiKey,
-  createApiKeyManagement,
-  normalizeApiKeyHeaderName,
-} from "./apiKeys";
-import type { ApiKeyManagementAPI } from "./apiKeys";
-import { createDatabasePluginCore } from "./db/databasePluginCore";
-import { createSchemaReadinessChecker } from "./db/schemaReadiness";
-import {
-  type DatabaseAdapterCapabilities,
-  type DatabaseAPI,
-  type DatabasePlugin,
-  isDatabasePlugin,
-} from "./db/types";
-import { createHotUpdaterHandlers, type HotUpdaterHandlers } from "./handler";
-import { createInsightsProvider } from "./insights/provider";
-import type { InsightsProvider } from "./insights/types";
-import { createStorageAccess } from "./storageAccess";
-
-export type RuntimeHotUpdaterAPI = DatabaseAPI & {
-  readonly handlers: HotUpdaterHandlers;
-  readonly adapterName: string;
-  /**
-   * Built-in Insights provider. Client ingestion and admin query routes are
-   * always mounted; React Native clients report lifecycle events by default
-   * and can opt out with `HotUpdater.init({ insights: false })`.
-   */
-  readonly insights: InsightsProvider;
-  /**
-   * In-process API key lifecycle operations for trusted server tooling.
-   * Creation returns the plaintext once; list and revoke expose only metadata.
-   * This capability is never mounted on the client or admin HTTP handlers.
-   */
-  readonly apiKeys: ApiKeyManagementAPI;
-};
-
-export type HotUpdaterAPI = RuntimeHotUpdaterAPI;
-
-export type ClientAccessPolicy =
-  | {
-      /**
-       * Leaves Release Catalog, artifact, and Insights ingestion routes
-       * publicly accessible without a client credential.
-       */
-      readonly type: "public";
-    }
-  | {
-      /**
-       * Requires a key registered in `database.models.apiKeys` for
-       * Release Catalog, artifact, and Insights ingestion requests.
-       */
-      readonly type: "api-key";
-      /**
-       * Request header containing the API key. Defaults to
-       * `x-api-key`. Clients must send the same header; Release Catalog
-       * responses include it in `Vary` to preserve cache isolation.
-       */
-      readonly headerName?: string;
-    };
-
-export interface CreateHotUpdaterOptions {
-  readonly database: DatabasePlugin;
-  /**
-   * Required client-route access policy. This choice is explicit so a server
-   * cannot accidentally change between public and authenticated OTA access.
-   * `/version`, storage downloads, and admin-handler routes are unaffected.
-   */
-  readonly clientAccess: ClientAccessPolicy;
-  /** Storage implementations used to read provider-specific storage URIs. */
-  readonly storage?: readonly StoragePlugin[];
-}
-
-const normalizeClientAccess = (
-  value: unknown,
-):
-  | { readonly type: "public" }
-  | {
-      readonly type: "api-key";
-      readonly headerName: string;
-    } => {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError("clientAccess must be an object.");
-  }
-  const policy = value as {
-    readonly headerName?: unknown;
-    readonly type?: unknown;
-  };
-  if (policy.type === "public") return { type: "public" };
-  if (policy.type === "api-key") {
-    return {
-      headerName: normalizeApiKeyHeaderName(policy.headerName),
-      type: "api-key",
-    };
-  }
-  throw new TypeError(
-    'clientAccess.type must be either "public" or "api-key".',
-  );
-};
-
-type DatabasePluginCore = {
-  readonly api: DatabaseAPI;
-  readonly adapterName: string;
-  readonly createMigrator: () => never;
-  readonly generateSchema: () => never;
-};
-
-export const hotUpdaterCoreMetadata = Symbol.for(
-  "@hot-updater/server/core-metadata",
-);
-
-export type HotUpdaterCoreMetadata = {
-  readonly adapterCapabilities: DatabaseAdapterCapabilities;
-  readonly core: DatabasePluginCore;
-};
-
-export type HotUpdaterCore = {
-  readonly api: RuntimeHotUpdaterAPI;
-  readonly adapterCapabilities: DatabaseAdapterCapabilities;
-  readonly core: DatabasePluginCore;
-};
-
-export function getHotUpdaterCoreMetadata(
-  hotUpdater: RuntimeHotUpdaterAPI,
-): HotUpdaterCoreMetadata | undefined {
-  return (
-    hotUpdater as RuntimeHotUpdaterAPI & {
-      readonly [hotUpdaterCoreMetadata]?: HotUpdaterCoreMetadata;
-    }
-  )[hotUpdaterCoreMetadata];
-}
-
-export function createHotUpdaterCore(
-  options: CreateHotUpdaterOptions,
-): HotUpdaterCore {
-  for (const key of ["authorityId", "catalogId"]) {
-    if (Object.hasOwn(options, key)) {
-      throw new TypeError(
-        `Remove ${key} from createHotUpdater options. Catalog identity is managed internally.`,
-      );
-    }
-  }
-  const database = options.database;
-  const storagePlugins = (options.storage ?? []).map((storage) => {
-    assertStorageOperations(storage, ["get", "getDownloadUrl"]);
-    return storage;
-  });
-  const { downloadStorageObject, readStorageText, resolveFileUrl } =
-    createStorageAccess(storagePlugins);
-  const adapterCapabilities: DatabaseAdapterCapabilities = database;
-
-  if (!isDatabasePlugin(database)) {
-    throw new Error("@hot-updater/server only supports database plugins.");
-  }
-
-  const plugin: DatabasePlugin = database;
-  const adapterName = adapterCapabilities.adapterName ?? plugin.name;
-  const assertSchemaReady = createSchemaReadinessChecker(
-    adapterName,
-    adapterCapabilities.createMigrator,
-  );
-  const core = createDatabasePluginCore(plugin, resolveFileUrl, {
-    beforeOperation: assertSchemaReady,
-    readStorageText,
-  });
-  const clientAccess = normalizeClientAccess(options.clientAccess);
-  const insightsModel: InsightsModel = {
-    async record(input) {
-      await assertSchemaReady();
-      return plugin.models.insights.record(input);
-    },
-    async listEvents(input) {
-      await assertSchemaReady();
-      return plugin.models.insights.listEvents(input);
-    },
-    async findInstallations(input) {
-      await assertSchemaReady();
-      return plugin.models.insights.findInstallations(input);
-    },
-    async countInstallations(input) {
-      await assertSchemaReady();
-      return plugin.models.insights.countInstallations(input);
-    },
-    async countEvents(input) {
-      await assertSchemaReady();
-      return plugin.models.insights.countEvents(input);
-    },
-  };
-  const insights = createInsightsProvider(insightsModel);
-  const apiKeys = createApiKeyManagement({
-    apiKeys: plugin.models.apiKeys,
-    beforeOperation: assertSchemaReady,
-  });
-
-  const handlers = createHotUpdaterHandlers(
-    core.api,
-    insights,
-    clientAccess.type === "api-key"
-      ? {
-          authenticate: (request) =>
-            authenticateApiKey({
-              apiKeys: plugin.models.apiKeys,
-              beforeLookup: assertSchemaReady,
-              headerName: clientAccess.headerName,
-              request,
-            }),
-          headerName: clientAccess.headerName,
-        }
-      : undefined,
-    downloadStorageObject,
-  );
-
-  const api: RuntimeHotUpdaterAPI = Object.assign(
-    {
-      adapterName: adapterCapabilities.adapterName ?? core.adapterName,
-      insights,
-      apiKeys,
-      handlers,
-    },
-    core.api,
-  );
-  Object.defineProperty(api, hotUpdaterCoreMetadata, {
-    enumerable: false,
-    value: {
-      adapterCapabilities,
-      core,
-    } satisfies HotUpdaterCoreMetadata,
-  });
-
-  return {
-    api,
-    adapterCapabilities,
-    core,
-  };
-}
-
-export function createHotUpdater(
-  options: CreateHotUpdaterOptions,
-): RuntimeHotUpdaterAPI {
-  return createHotUpdaterCore(options).api;
-}