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

package/src/plugins/api-keys/apiKeysPlugin.spec.ts

@@ -0,0 +1,172 @@
+import {
+  createMemoryAdapter,
+  type DatabaseAdapter,
+} from "@hot-updater/plugin-core/internal";
+import { describe, expect, it, vi } from "vitest";
+
+import { createHotUpdater } from "../../createHotUpdaterCore";
+import { definePlugin } from "../definePlugin";
+import { apiKeys } from "./index";
+
+const API_KEY = "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE";
+
+/** A client endpoint with a cacheable answer, to see the policy's Vary. */
+const cached = definePlugin({
+  id: "cached",
+  schemaVersion: "1",
+  schema: {},
+  init: () => ({
+    api: {},
+    endpoints: [
+      {
+        method: "GET",
+        path: "/cached",
+        access: "client",
+        handler: async () =>
+          new Response("ok", {
+            headers: { "cache-control": "public, max-age=60" },
+          }),
+      },
+    ],
+  }),
+});
+
+const start = (
+  options: { headerName?: string; adapter?: DatabaseAdapter } = {},
+) => {
+  const hotUpdater = createHotUpdater({
+    database: {
+      name: "memory",
+      adapter: options.adapter ?? createMemoryAdapter(),
+    },
+    plugins: [
+      apiKeys(
+        options.headerName === undefined
+          ? {}
+          : { headerName: options.headerName },
+      ),
+      cached,
+    ],
+  });
+  const client = (
+    path: string,
+    headers: Record<string, string> = {},
+    init: RequestInit = {},
+  ) =>
+    hotUpdater.handlers.client(
+      new Request(`https://updates.example.com${path}`, { ...init, headers }),
+    );
+  return { hotUpdater, client };
+};
+
+describe("API keys plugin", () => {
+  it("protects every client route but /version with a registered, active key", async () => {
+    const { hotUpdater, client } = start();
+    await hotUpdater.api.apiKeys.register({ apiKey: API_KEY, name: "App" });
+    const catalog = "/release-catalogs/app-version/ios/production/1.0.0";
+
+    expect((await client("/version")).status).toBe(200);
+    expect((await client(catalog)).status).toBe(401);
+    expect((await client(catalog, { "x-api-key": "not-a-key" })).status).toBe(
+      401,
+    );
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(
+      (await client("/events", {}, { method: "POST", body: "{" })).status,
+    ).toBe(401);
+    expect(warn).not.toHaveBeenCalled();
+    // Past the key, /events answers that Insights is off: no insights() here.
+    const events = await client(
+      "/events",
+      { "x-api-key": API_KEY },
+      { method: "POST", body: "{" },
+    );
+    expect(events.status).toBe(204);
+    expect(events.headers.get("x-hot-updater-insights")).toBe("disabled");
+    expect(warn).toHaveBeenCalledOnce();
+    warn.mockRestore();
+    const allowed = await client("/cached", { "x-api-key": API_KEY });
+    expect(allowed.status).toBe(200);
+    expect(allowed.headers.get("vary")).toBe("x-api-key");
+  });
+
+  it("creates keys once in plaintext, lists and revokes them without hashes", async () => {
+    const { hotUpdater, client } = start();
+    const created = await hotUpdater.api.apiKeys.create({ name: " Deploy " });
+    expect(created.record).toMatchObject({
+      name: "Deploy",
+      prefix: created.apiKey.slice(0, 6),
+      role: "client",
+      revoked_at_ms: null,
+    });
+    const listed = await hotUpdater.api.apiKeys.list();
+    expect(listed).toEqual([created.record]);
+    expect(JSON.stringify(listed)).not.toContain("hash");
+    expect(
+      (await client("/cached", { "x-api-key": created.apiKey })).status,
+    ).toBe(200);
+
+    await expect(
+      hotUpdater.api.apiKeys.revoke({ id: created.record.id }),
+    ).resolves.toMatchObject({
+      id: created.record.id,
+      revoked_at_ms: expect.any(Number),
+    });
+    expect(
+      (await client("/cached", { "x-api-key": created.apiKey })).status,
+    ).toBe(401);
+    await expect(
+      hotUpdater.api.apiKeys.revoke({ id: "missing" }),
+    ).resolves.toBeNull();
+  });
+
+  it("provisions a saved key idempotently and a new key otherwise", async () => {
+    const { hotUpdater } = start();
+    const first = await hotUpdater.api.apiKeys.provision({
+      existingApiKey: API_KEY,
+      name: "Managed",
+    });
+    const again = await hotUpdater.api.apiKeys.provision({
+      existingApiKey: ` ${API_KEY} `,
+      name: "Managed",
+    });
+    expect(again.record.id).toBe(first.record.id);
+    const fresh = await hotUpdater.api.apiKeys.provision({ name: "Managed" });
+    expect(fresh.apiKey).not.toBe(API_KEY);
+    expect(await hotUpdater.api.apiKeys.list()).toHaveLength(2);
+  });
+
+  it("reads keys only from the configured header and varies by it", async () => {
+    const { hotUpdater, client } = start({ headerName: "X-Hot-Updater-Key" });
+    await hotUpdater.api.apiKeys.register({ apiKey: API_KEY, name: "App" });
+
+    expect((await client("/cached", { "x-api-key": API_KEY })).status).toBe(
+      401,
+    );
+    const allowed = await client("/cached", { "x-hot-updater-key": API_KEY });
+    expect(allowed.status).toBe(200);
+    expect(allowed.headers.get("vary")).toBe("x-hot-updater-key");
+    expect(() => apiKeys({ headerName: "invalid header" })).toThrow(
+      "must name a valid header",
+    );
+  });
+
+  it("answers 503 when credential storage is unavailable", async () => {
+    const memory = createMemoryAdapter();
+    const { client } = start({
+      adapter: {
+        ...memory,
+        get: async () => {
+          throw new Error("storage unavailable");
+        },
+        query: async () => {
+          throw new Error("storage unavailable");
+        },
+      },
+    });
+    expect((await client("/cached", { "x-api-key": API_KEY })).status).toBe(
+      503,
+    );
+    expect((await client("/version")).status).toBe(200);
+  });
+});

package/src/plugins/api-keys/index.ts

@@ -0,0 +1,66 @@
+import {
+  API_KEY_HEADER_NAME,
+  authenticateApiKey,
+  createApiKeyManagement,
+  normalizeApiKeyHeaderName,
+  provisionApiKey,
+  registerApiKey,
+} from "../../apiKeys";
+import { markBuiltIn } from "../builtIn";
+import { definePlugin } from "../definePlugin";
+import { createApiKeyModel } from "./model";
+import { apiKeysSchema } from "./schema";
+
+export { createApiKeyModel } from "./model";
+export { apiKeysSchema, type ApiKeysSchema } from "./schema";
+
+export interface ApiKeysOptions {
+  /** The request header that carries the key; defaults to `x-api-key`. */
+  readonly headerName?: string;
+}
+
+/**
+ * Built-in API keys: protects client routes with keys whose SHA-256 digests
+ * are stored, and manages them in-process.
+ */
+export const apiKeys = (options: ApiKeysOptions = {}) => {
+  const headerName = normalizeApiKeyHeaderName(
+    options.headerName ?? API_KEY_HEADER_NAME,
+  );
+  return markBuiltIn(
+    definePlugin({
+      id: "apiKeys",
+      provides: { clientAuth: true },
+      schemaVersion: "1.0.0",
+      schema: apiKeysSchema,
+      init: ({ db }) => {
+        const model = createApiKeyModel(db);
+        return {
+          api: {
+            ...createApiKeyManagement({ apiKeys: model }),
+            /** Registers a known plaintext key idempotently, for managed init. */
+            register: (input: {
+              readonly apiKey: string;
+              readonly name: string;
+              readonly createdAtMs?: number;
+            }) => registerApiKey({ ...input, apiKeys: model }),
+            /** Reuses a saved key or creates one, for managed init. */
+            provision: (input: {
+              readonly existingApiKey?: string;
+              readonly name: string;
+            }) => provisionApiKey({ ...input, apiKeys: model }),
+          },
+          clientAuth: {
+            varyHeaders: [headerName],
+            authenticate: (headers: Headers) =>
+              authenticateApiKey({
+                apiKeys: model,
+                headerName,
+                request: { headers } as Request,
+              }),
+          },
+        };
+      },
+    }),
+  );
+};

package/src/plugins/api-keys/model.ts

@@ -0,0 +1,69 @@
+import type { ApiKeyModel, ApiKeyRow } from "@hot-updater/plugin-core";
+
+import type { HotUpdaterDatabase } from "../../database/database";
+import { DatabaseConstraintError } from "../../database/errors";
+import type { ApiKeysSchema } from "./schema";
+
+const toRow = (row: Readonly<Record<string, unknown>>): ApiKeyRow =>
+  ({
+    id: row.id,
+    hash: row.hash,
+    name: row.name,
+    prefix: row.prefix,
+    role: row.role,
+    created_at_ms: row.created_at_ms,
+    revoked_at_ms: row.revoked_at_ms,
+  }) as ApiKeyRow;
+
+/** Today's `ApiKeyModel` on the engine: one unique read by hash, keyed writes. */
+export const createApiKeyModel = (
+  db: HotUpdaterDatabase<ApiKeysSchema>,
+): ApiKeyModel => ({
+  async create(row) {
+    try {
+      return await db.transaction(async (tx) => {
+        if ((await tx.findOne("api_keys", { hash: row.hash })) !== null) {
+          return "existing" as const;
+        }
+        tx.create("api_keys", row);
+        return "created" as const;
+      });
+    } catch (error) {
+      if (error instanceof DatabaseConstraintError && error.reason === "unique")
+        return "existing";
+      throw error;
+    }
+  },
+  async findByHash(hash) {
+    const row = await db.findOne("api_keys", { hash });
+    return row === null ? null : toRow(row);
+  },
+  /** Every key, newest first, then by id; the whole list is the result. */
+  async list() {
+    const rows: ApiKeyRow[] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await db.findMany("api_keys", {
+        index: "byCreated",
+        where: {},
+        order: "desc",
+        limit: 500,
+        ...(cursor === undefined ? {} : { cursor }),
+      });
+      rows.push(...page.rows.map(toRow));
+      cursor = page.next;
+    } while (cursor !== undefined);
+    return rows.sort(
+      (left, right) =>
+        right.created_at_ms - left.created_at_ms ||
+        (left.id < right.id ? -1 : left.id > right.id ? 1 : 0),
+    );
+  },
+  revoke: ({ id, revokedAtMs }) =>
+    db.transaction(async (tx) => {
+      const row = await tx.findOne("api_keys", { id });
+      if (row === null) return null;
+      tx.update("api_keys", row, { revoked_at_ms: revokedAtMs });
+      return toRow({ ...row, revoked_at_ms: revokedAtMs });
+    }),
+});

package/src/plugins/api-keys/schema.ts

@@ -0,0 +1,22 @@
+import { defineTable } from "../../database/schema";
+
+/** v1's `api_keys` columns; the plaintext key is never stored, only its SHA-256 digest. */
+export const apiKeysSchema = {
+  api_keys: defineTable(
+    {
+      id: { type: "string", maxLength: 255 },
+      hash: { type: "string", maxLength: 64, unique: true },
+      name: { type: "string", maxLength: 64 },
+      prefix: { type: "string", maxLength: 16 },
+      role: { type: "string", maxLength: 16 },
+      created_at_ms: { type: "integer" },
+      revoked_at_ms: { type: "integer", required: false },
+    },
+    {
+      key: ["id"],
+      indexes: { byCreated: { eq: [], sort: ["created_at_ms"] } },
+    },
+  ),
+} as const;
+
+export type ApiKeysSchema = typeof apiKeysSchema;

package/src/plugins/builtIn.ts

@@ -0,0 +1,5 @@
+/** Marks built-in plugins, whose tables keep their names instead of taking the plugin id as a namespace. */
+export const builtInPlugin = Symbol.for("@hot-updater/server/built-in-plugin");
+
+export const markBuiltIn = <TPlugin extends object>(plugin: TPlugin): TPlugin =>
+  Object.defineProperty(plugin, builtInPlugin, { value: true });

package/src/plugins/definePlugin.ts

@@ -0,0 +1,100 @@
+import type { CoreReads } from "../core/reads";
+import type { HotUpdaterDatabase } from "../database/database";
+import type { ModuleSchema } from "../database/schema";
+
+export type PluginEndpointMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface PluginEndpoint {
+  readonly method: PluginEndpointMethod;
+  /** Relative to the handler's mount; `:name` segments become `params`. */
+  readonly path: string;
+  /**
+   * `"client"` mounts on `handlers.client` behind the client-route policy;
+   * `"admin"` mounts on `handlers.admin`, which the host protects.
+   */
+  readonly access: "client" | "admin";
+  readonly handler: (
+    request: Request,
+    params: Readonly<Record<string, string>>,
+  ) => Promise<Response>;
+}
+
+/** The client-route policy a plugin provides, such as API keys. */
+export interface ClientAuth {
+  /** Request headers the decision reads; core adds them to `Vary` on cacheable client responses. */
+  readonly varyHeaders: readonly string[];
+  /** Whether the request may use client routes; a throw answers 503. */
+  authenticate(headers: Headers): Promise<boolean>;
+}
+
+export interface PluginInstance<Api = unknown> {
+  readonly api: Api;
+  readonly endpoints?: readonly PluginEndpoint[];
+  readonly clientAuth?: ClientAuth;
+}
+
+/** Core's reads: bundles, Releases, Catalogs, and channels, each through a declared index. Plugins never write core. */
+export type CoreReader = CoreReads;
+
+export interface PluginContext<S extends ModuleSchema> {
+  /** The plugin's own tables and aggregates. */
+  readonly db: HotUpdaterDatabase<S>;
+  readonly core: CoreReader;
+  now(): number;
+}
+
+export interface PluginProvides {
+  readonly clientAuth?: true;
+}
+
+/** An instance whose `clientAuth` matches what the plugin declares it provides. */
+export type InstanceFor<TProvides, TInstance> = TProvides extends {
+  readonly clientAuth: true;
+}
+  ? TInstance & { readonly clientAuth: ClientAuth }
+  : TInstance & {
+      readonly clientAuth?: "Declare provides: { clientAuth: true } to return clientAuth";
+    };
+
+export interface HotUpdaterPlugin<
+  TId extends string = string,
+  TSchema extends ModuleSchema = ModuleSchema,
+  TInstance extends PluginInstance = PluginInstance,
+  TProvides extends PluginProvides = PluginProvides,
+> {
+  readonly id: TId;
+  /** Static, so the type system and startup can count client-route policies. */
+  readonly provides?: TProvides;
+  /** Stored under the settings key `schema.<id>`. */
+  readonly schemaVersion: string;
+  readonly schema: TSchema;
+  /** Called once at startup, synchronously. */
+  init(context: PluginContext<TSchema>): TInstance;
+  /** Only core modules carry a kind. */
+  readonly kind?: "Core is built in; it is not a plugin";
+}
+
+/** Declares a plugin; built-in and third-party plugins use the same contract. */
+export const definePlugin = <
+  const TId extends string,
+  const TSchema extends ModuleSchema,
+  TInstance extends PluginInstance,
+  const TProvides extends PluginProvides = {},
+>(plugin: {
+  readonly id: TId;
+  readonly provides?: TProvides;
+  readonly schemaVersion: string;
+  readonly schema: TSchema;
+  init(context: PluginContext<TSchema>): InstanceFor<TProvides, TInstance>;
+}): HotUpdaterPlugin<TId, TSchema, TInstance, TProvides> =>
+  plugin as HotUpdaterPlugin<TId, TSchema, TInstance, TProvides>;
+
+/** Any plugin, whatever its schema and API. */
+export type AnyHotUpdaterPlugin = HotUpdaterPlugin<string, any, any, any>;
+
+/** Each plugin's API by id. */
+export type PluginApis<TPlugins extends readonly AnyHotUpdaterPlugin[]> = {
+  readonly [TPlugin in TPlugins[number] as TPlugin["id"]]: ReturnType<
+    TPlugin["init"]
+  >["api"];
+};

package/src/plugins/index.ts

@@ -0,0 +1,55 @@
+/**
+ * The plugin authoring API. Built-in and third-party plugins declare their
+ * tables and aggregates here and receive a typed database handle in `init`.
+ */
+export {
+  definePlugin,
+  type AnyHotUpdaterPlugin,
+  type ClientAuth,
+  type CoreReader,
+  type HotUpdaterPlugin,
+  type InstanceFor,
+  type PluginApis,
+  type PluginContext,
+  type PluginEndpoint,
+  type PluginEndpointMethod,
+  type PluginInstance,
+  type PluginProvides,
+} from "./definePlugin";
+export {
+  defineAggregate,
+  defineTable,
+  type AggregateDefinition,
+  type DerivedDefinition,
+  type FieldDefinition,
+  type FieldReference,
+  type FieldType,
+  type IndexDefinition,
+  type ModuleSchema,
+  type ReferenceAction,
+  type TableDefinition,
+} from "../database/schema";
+export type {
+  AggregateChanges,
+  AggregateIdentity,
+  AggregateRow,
+  CreateRow,
+  HotUpdaterDatabase,
+  HotUpdaterTransaction,
+  Lookup,
+  ReadOptions,
+  ReadRow,
+  TableRow,
+  UpdateSet,
+} from "../database/database";
+export type { Page } from "../database/engineReads";
+export {
+  DatabaseAmbiguousCommitError,
+  DatabaseConflictError,
+  DatabaseConstraintError,
+  DatabaseTransactionError,
+  type ConstraintReason,
+} from "../database/errors";
+export { DatabaseQueryError } from "../database/engineReads";
+export { DatabaseCursorError } from "../database/cursor";
+export { HotUpdaterConfigError } from "../assembly/assemblePlugins";

package/src/plugins/insights/index.ts

@@ -0,0 +1,86 @@
+import type {
+  BundleEventRow,
+  InsightsCountEventsInput,
+  InsightsCountLatestEventsInput,
+  InsightsFindLatestEventsInput,
+  InsightsGetAppUsageInput,
+  InsightsGetReleaseActivityInput,
+  InsightsListEventsInput,
+} from "@hot-updater/plugin-core";
+
+import type { HotUpdaterDatabase } from "../../database/database";
+import { createInsightsProvider } from "../../insights/provider";
+import {
+  createInsightsRouteHandlers,
+  INSIGHTS_ROUTES,
+} from "../../insights/routes";
+import { markBuiltIn } from "../builtIn";
+import { definePlugin } from "../definePlugin";
+import { createInsightsModel } from "./model";
+import {
+  countEvents,
+  countLatestEvents,
+  findLatestEvents,
+  getAppUsage,
+  getReleaseActivity,
+  listEvents,
+} from "./reads";
+import { recordEvent } from "./recordEvent";
+import { insightsSchema, type InsightsSchema } from "./schema";
+
+export { createInsightsModel } from "./model";
+export { insightsIdentity, type InsightsIdentityParts } from "./recordEvent";
+export { insightsSchema, type InsightsSchema } from "./schema";
+
+const createInsightsApi = (
+  db: HotUpdaterDatabase<InsightsSchema>,
+  now: () => number,
+) => ({
+  /** Records one validated event row; a repeated id changes nothing. */
+  recordEvent: (event: BundleEventRow) => recordEvent(db, event),
+  listEvents: (input: InsightsListEventsInput) => listEvents(db, input),
+  findLatestEvents: (input: InsightsFindLatestEventsInput) =>
+    findLatestEvents(db, input),
+  countLatestEvents: (input: InsightsCountLatestEventsInput) =>
+    countLatestEvents(db, input),
+  countEvents: (input: InsightsCountEventsInput) => countEvents(db, input),
+  getReleaseActivity: (input: InsightsGetReleaseActivityInput) =>
+    getReleaseActivity(db, input, now),
+  getAppUsage: (input: InsightsGetAppUsageInput) => getAppUsage(db, input, now),
+});
+
+export type InsightsApi = ReturnType<typeof createInsightsApi>;
+
+/**
+ * Built-in Insights: bundle lifecycle events, each installation's latest
+ * event, and the counters, gauges, and sketches its reads come from. It
+ * serves `POST /events` to clients and the Insights reads to admins.
+ */
+export const insights = () =>
+  markBuiltIn(
+    definePlugin({
+      id: "insights",
+      schemaVersion: "1.0.0",
+      schema: insightsSchema,
+      init: ({ db, now }) => {
+        const api = createInsightsApi(db, now);
+        const routes = createInsightsRouteHandlers(
+          createInsightsProvider(createInsightsModel(api)),
+        );
+        return {
+          api,
+          endpoints: INSIGHTS_ROUTES.map(
+            ({ access, method, path, handler }) => ({
+              access,
+              method,
+              path,
+              handler: (
+                request: Request,
+                params: Readonly<Record<string, string>>,
+              ) => routes[handler](params, request),
+            }),
+          ),
+        };
+      },
+    }),
+  );