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

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

@@ -1,214 +0,0 @@
-import type { ApiKeyModel, ApiKeyRow } from "./model";
-
-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("apiKeys({ headerName }) must name a valid header.");
-  }
-
-  try {
-    const headers = new Headers();
-    headers.set(value, "");
-    return headers.keys().next().value!;
-  } catch {
-    throw new TypeError("apiKeys({ headerName }) must name a valid header.");
-  }
-};
-
-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 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);
-  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;
-}): ApiKeyManagementAPI =>
-  Object.freeze({
-    async create({ name }: { readonly name: string }) {
-      const created = await createApiKey({ apiKeys: input.apiKeys, name });
-      return Object.freeze({
-        apiKey: created.apiKey,
-        record: created.record,
-      });
-    },
-    async list() {
-      return Object.freeze((await input.apiKeys.list()).map(toApiKeyMetadata));
-    },
-    async revoke({ id }: { readonly id: string }) {
-      const record = await input.apiKeys.revoke({
-        id,
-        revokedAtMs: Date.now(),
-      });
-      return record === null ? null : toApiKeyMetadata(record);
-    },
-  });

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

@@ -1,168 +0,0 @@
-import {
-  createMemoryAdapter,
-  type DatabaseAdapter,
-} from "@hot-updater/plugin-core/internal";
-import { describe, expect, it } 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,
-    );
-    // No insights() here, so /events is no route, with or without a key.
-    const keyed: readonly Record<string, string>[] = [
-      {},
-      { "x-api-key": API_KEY },
-    ];
-    for (const headers of keyed) {
-      expect(
-        (await client("/events", headers, { method: "POST", body: "{" }))
-          .status,
-      ).toBe(404);
-    }
-    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/cli.spec.ts

@@ -1,187 +0,0 @@
-import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
-import { describe, expect, it, vi } from "vitest";
-
-import { createDatabasePluginApis } from "../../assembly/databasePlugins";
-import type { PluginCommand, PluginCommandUi } from "../definePlugin";
-import type { ApiKeyMetadata } from "./apiKeys";
-import { type ApiKeysCliApi, apiKeysCli } from "./cli";
-import { apiKeys } from "./index";
-
-/** A UI that keeps what the command writes, unstyled. */
-const createUi = () => {
-  const output = { messages: [] as string[], warnings: [] as string[] };
-  const printed: string[] = [];
-  const ui: PluginCommandUi = {
-    block: (heading, lines) => [heading, ...lines].join("\n"),
-    kv: (label, value) => `${label}: ${value}`,
-    table: (columns, rows) =>
-      rows
-        .map((row) => columns.map(({ key }) => row[key]).join(" | "))
-        .join("\n"),
-    id: (value) => value,
-    muted: (value) => value,
-    success: (value) => value,
-    danger: (value) => value,
-    warning: (value) => value,
-    message: (text) => output.messages.push(text),
-    info: (text) => output.messages.push(text),
-    warn: (text) => output.warnings.push(text),
-    print: (text) => printed.push(text),
-    confirm: vi.fn(async () => {}),
-  };
-  return { ui, output, printed };
-};
-
-const command = (name: string): PluginCommand<ApiKeysCliApi> => {
-  const group = apiKeysCli("x-api-key").commands?.[0];
-  const found = group?.commands?.find((candidate) => candidate.name === name);
-  if (found?.run === undefined) throw new Error(`No ${name} command.`);
-  return found;
-};
-
-/** The apiKeys() plugin's API over a memory adapter, as the CLI assembles it. */
-const assemble = () =>
-  createDatabasePluginApis({ name: "memory", adapter: createMemoryAdapter() }, [
-    apiKeys(),
-  ]).apiKeys;
-
-describe("apiKeys() CLI commands", () => {
-  it("adds `hot-updater api-key` with create, list, and revoke", () => {
-    const [group] = apiKeysCli("x-api-key").commands ?? [];
-    expect(group?.name).toBe("api-key");
-    expect(group?.commands?.map(({ name }) => name)).toEqual([
-      "create",
-      "list",
-      "revoke",
-    ]);
-    expect(apiKeys().cli?.commands?.map(({ name }) => name)).toEqual([
-      "api-key",
-    ]);
-  });
-
-  it("creates a key and prints its plaintext exactly once", async () => {
-    const api = assemble();
-    const { ui, output } = createUi();
-
-    await command("create").run!({
-      api,
-      args: {},
-      options: { name: "Production app" },
-      ui,
-    });
-
-    const [record] = await api.list();
-    expect(record?.name).toBe("Production app");
-    const printed = output.messages.join("\n");
-    const apiKey = /API key: (\S+)/u.exec(printed)?.[1];
-    expect(apiKey).toMatch(/^[A-Za-z0-9_-]{43}$/u);
-    expect(printed.split(apiKey!).length - 1).toBe(1);
-    expect(JSON.stringify(record)).not.toContain(apiKey);
-    expect(output.warnings).toEqual([
-      "Save this API key now. It will not be shown again.",
-    ]);
-  });
-
-  it("lists JSON metadata newest first, without hashes or plaintext", async () => {
-    const api = assemble();
-    const older = await api.create({ name: "Older" });
-    await new Promise((resolve) => setTimeout(resolve, 2));
-    const newer = await api.create({ name: "Newer" });
-    const { ui, printed } = createUi();
-
-    await command("list").run!({ api, args: {}, options: { json: true }, ui });
-
-    const json = printed.join("\n");
-    const records = JSON.parse(json) as ApiKeyMetadata[];
-    expect(records.map(({ id }) => id)).toEqual([
-      newer.record.id,
-      older.record.id,
-    ]);
-    expect(json).not.toContain("hash");
-    expect(json).not.toContain(older.apiKey);
-  });
-
-  it("lists a table, or says there are no keys", async () => {
-    const api = assemble();
-    const empty = createUi();
-    await command("list").run!({
-      api,
-      args: {},
-      options: {},
-      ui: empty.ui,
-    });
-    expect(empty.output.messages).toEqual(["(no API keys)"]);
-
-    const created = await api.create({ name: "Production app" });
-    await api.revoke({ id: created.record.id });
-    const listed = createUi();
-    await command("list").run!({
-      api,
-      args: {},
-      options: {},
-      ui: listed.ui,
-    });
-    expect(listed.output.messages[0]).toContain(
-      `${created.record.id} | Production app | ${created.apiKey.slice(0, 6)} | revoked`,
-    );
-  });
-
-  it("confirms before revoking unless --yes is set", async () => {
-    const api = assemble();
-    const created = await api.create({ name: "Production app" });
-    const { ui, output } = createUi();
-
-    await command("revoke").run!({
-      api,
-      args: { id: created.record.id },
-      options: {},
-      ui,
-    });
-
-    expect(ui.confirm).toHaveBeenCalledWith(
-      `Revoke API key ${created.record.id}?`,
-    );
-    await expect(api.list()).resolves.toMatchObject([
-      { id: created.record.id, revoked_at_ms: expect.any(Number) },
-    ]);
-    expect(output.messages[0]).toContain("API key revoked");
-
-    const skipped = createUi();
-    await command("revoke").run!({
-      api,
-      args: { id: created.record.id },
-      options: { yes: true },
-      ui: skipped.ui,
-    });
-    expect(skipped.ui.confirm).not.toHaveBeenCalled();
-  });
-
-  it("fails to revoke a key it does not have", async () => {
-    const { ui } = createUi();
-    await expect(
-      command("revoke").run!({
-        api: assemble(),
-        args: { id: "api-missing" },
-        options: { yes: true },
-        ui,
-      }),
-    ).rejects.toThrow('API key "api-missing" was not found.');
-  });
-
-  it("gives init the app's key: a saved one again, else a new one", async () => {
-    const credential = apiKeys({ headerName: "X-Hot-Updater-Key" }).cli
-      ?.clientCredential;
-    expect(credential).toMatchObject({
-      label: "API key",
-      header: "x-hot-updater-key",
-      env: "HOT_UPDATER_API_KEY",
-    });
-    const api = assemble();
-    const created = await credential!.provision(api, { name: "Init" });
-    expect(created).toMatch(/^[A-Za-z0-9_-]{43}$/u);
-    await expect(
-      credential!.provision(api, { existing: created, name: "Init again" }),
-    ).resolves.toBe(created);
-    await expect(api.list()).resolves.toHaveLength(1);
-  });
-});

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

@@ -1,140 +0,0 @@
-import type { PluginCli, PluginCommandUi } from "../definePlugin";
-import type {
-  ApiKeyManagementAPI,
-  ApiKeyMetadata,
-  CreatedApiKey,
-} from "./apiKeys";
-
-/** The part of the apiKeys() API the CLI uses. */
-export interface ApiKeysCliApi extends ApiKeyManagementAPI {
-  provision(input: {
-    readonly existingApiKey?: string;
-    readonly name: string;
-  }): Promise<CreatedApiKey>;
-}
-
-/** The environment variable init stores the app's API key in. */
-export const API_KEY_ENV = "HOT_UPDATER_API_KEY";
-
-/** A new API key: 32 random bytes, base64url, as the plugin creates them. */
-const generateApiKey = (): string => {
-  const bytes = crypto.getRandomValues(new Uint8Array(32));
-  return btoa(String.fromCharCode(...bytes))
-    .replaceAll("+", "-")
-    .replaceAll("/", "_")
-    .replace(/=+$/u, "");
-};
-
-const formatList = (
-  ui: PluginCommandUi,
-  records: readonly ApiKeyMetadata[],
-): string =>
-  records.length === 0
-    ? ui.muted("(no API keys)")
-    : ui.table(
-        [
-          { key: "id", label: "ID", format: ui.id },
-          { key: "name", label: "Name" },
-          { key: "prefix", label: "Prefix", format: ui.muted },
-          {
-            key: "status",
-            label: "Status",
-            format: (value) =>
-              value.trim() === "active" ? ui.success(value) : ui.danger(value),
-          },
-          { key: "created", label: "Created", format: ui.muted },
-        ],
-        records.map((record) => ({
-          created: new Date(record.created_at_ms).toISOString(),
-          id: record.id,
-          name: record.name,
-          prefix: record.prefix,
-          status: record.revoked_at_ms === null ? "active" : "revoked",
-        })),
-      );
-
-/**
- * `hot-updater api-key create|list|revoke`, and the API key that init
- * provisions for an app, sent in `headerName`.
- */
-export const apiKeysCli = (headerName: string): PluginCli<ApiKeysCliApi> => ({
-  commands: [
-    {
-      name: "api-key",
-      description: "Manage API keys",
-      commands: [
-        {
-          name: "create",
-          description: "Create an API key",
-          options: [
-            {
-              flags: "--name <name>",
-              description: "name used to identify the API key",
-              required: true,
-            },
-          ],
-          async run({ api, options, ui }) {
-            const created = await api.create({ name: String(options.name) });
-            ui.message(
-              ui.block("API key created", [
-                ui.kv("Name", created.record.name),
-                ui.kv("ID", ui.id(created.record.id)),
-                ui.kv("API key", ui.warning(created.apiKey)),
-              ]),
-            );
-            ui.warn("Save this API key now. It will not be shown again.");
-          },
-        },
-        {
-          name: "list",
-          description: "List API keys",
-          options: [
-            { flags: "--json", description: "output API key metadata as JSON" },
-          ],
-          async run({ api, options, ui }) {
-            const records = [...(await api.list())].sort(
-              (left, right) => right.created_at_ms - left.created_at_ms,
-            );
-            if (options.json) ui.print(JSON.stringify(records, null, 2));
-            else ui.message(formatList(ui, records));
-          },
-        },
-        {
-          name: "revoke",
-          description: "Revoke an API key",
-          arguments: [{ name: "id", description: "API key id" }],
-          options: [
-            { flags: "-y, --yes", description: "skip confirmation prompt" },
-          ],
-          async run({ api, args, options, ui }) {
-            const id = String(args.id);
-            if (!options.yes) await ui.confirm(`Revoke API key ${id}?`);
-            const revoked = await api.revoke({ id });
-            if (revoked === null) {
-              throw new Error(`API key "${id}" was not found.`);
-            }
-            ui.message(
-              ui.block("API key revoked", [
-                ui.kv("Name", revoked.name),
-                ui.kv("ID", ui.id(revoked.id)),
-              ]),
-            );
-          },
-        },
-      ],
-    },
-  ],
-  clientCredential: {
-    label: "API key",
-    header: headerName,
-    env: API_KEY_ENV,
-    generate: generateApiKey,
-    provision: async (api, { existing, name }) =>
-      (
-        await api.provision({
-          ...(existing === undefined ? {} : { existingApiKey: existing }),
-          name,
-        })
-      ).apiKey,
-  },
-});