@hot-updater/console 1.1.4 → 1.2.0-rc.1

package/src/lib/server/local-console.ts

@@ -0,0 +1,164 @@
+/**
+ * The variable `hot-updater console` passes the console it starts its
+ * per-run session secret in. Without it, the local console serves no page
+ * and no server function.
+ */
+export const LOCAL_CONSOLE_SESSION_ENV = "HOT_UPDATER_CONSOLE_SESSION";
+
+/** The query parameter of the link `hot-updater console` prints. */
+export const LOCAL_CONSOLE_SESSION_PARAM = "hot-updater-session";
+
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+export interface LocalConsoleGuardOptions {
+  /** The run's session secret; without one, every page is refused. */
+  readonly session: string | undefined;
+  /** The port the console listens on; any loopback port when unknown. */
+  readonly port: string | undefined;
+  /**
+   * Whether to check the `Host` header. Vite's dev server checks it
+   * itself, against its `server.allowedHosts`.
+   */
+  readonly checkHost: boolean;
+}
+
+/** Compares in time that depends only on the lengths. */
+const sameSecret = (given: string, expected: string): boolean => {
+  if (given.length !== expected.length) return false;
+  let difference = 0;
+  for (let index = 0; index < given.length; index += 1) {
+    difference |= given.charCodeAt(index) ^ expected.charCodeAt(index);
+  }
+  return difference === 0;
+};
+
+/**
+ * The session cookie's name. Browsers send a cookie to every port of a
+ * host, so the port keeps two local consoles' sessions apart.
+ */
+const cookieName = (port: string | undefined) =>
+  port === undefined
+    ? "hot_updater_console_session"
+    : `hot_updater_console_session_${port}`;
+
+const cookieOf = (request: Request, name: string): string | undefined => {
+  for (const part of request.headers.get("cookie")?.split(";") ?? []) {
+    const separator = part.indexOf("=");
+    if (separator !== -1 && part.slice(0, separator).trim() === name) {
+      return part.slice(separator + 1).trim();
+    }
+  }
+  return undefined;
+};
+
+interface HostParts {
+  readonly hostname: string;
+  /** The port, `80` when the host names none, as HTTP's default. */
+  readonly port: string;
+}
+
+/** A port as digits without leading zeros, so `80` and `080` agree. */
+const normalPort = (port: string) => String(Number(port));
+
+/** A `Host` header's name and port, or undefined when it is not one. */
+const hostPartsOf = (host: string): HostParts | undefined => {
+  const match = /^(\[[0-9a-f:.]+\]|[a-z0-9.-]+)(?::(\d{1,5}))?$/iu.exec(host);
+  if (!match) return undefined;
+  return {
+    hostname: match[1]!.toLowerCase(),
+    port: normalPort(match[2] ?? "80"),
+  };
+};
+
+/** Whether `origin` is the plain-HTTP origin of `host`. */
+const isOriginOf = (origin: string, host: HostParts | undefined) => {
+  if (host === undefined) return false;
+  let parsed: URL;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return false;
+  }
+  return (
+    parsed.protocol === "http:" &&
+    parsed.hostname === host.hostname &&
+    normalPort(parsed.port || "80") === host.port
+  );
+};
+
+const refuse = (status: 401 | 403, message: string) =>
+  new Response(message, {
+    status,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": "text/plain; charset=utf-8",
+    },
+  });
+
+/**
+ * What the local console answers before a request reaches a page, a server
+ * function, or a route, or undefined to let it through:
+ *
+ * - a `Host` that is not this machine on the console's port is refused, so
+ *   a site that rebinds its name to 127.0.0.1 reaches nothing;
+ * - a request that changes something from another origin is refused;
+ * - the link `hot-updater console` prints carries the run's session secret,
+ *   which becomes an HttpOnly, SameSite=Strict cookie, and every other page
+ *   and server function needs that cookie, so another user of the machine
+ *   or a local process without the secret reaches nothing.
+ */
+export const guardLocalConsoleRequest = (
+  request: Request,
+  { session, port, checkHost }: LocalConsoleGuardOptions,
+): Response | undefined => {
+  const header = request.headers.get("host");
+  const host = header === null ? undefined : hostPartsOf(header);
+  if (
+    checkHost &&
+    (host === undefined ||
+      !LOOPBACK_HOSTNAMES.has(host.hostname) ||
+      (port !== undefined && host.port !== normalPort(port)))
+  ) {
+    return refuse(
+      403,
+      `This console answers only at http://localhost${port === undefined ? "" : `:${port}`}.`,
+    );
+  }
+  if (!SAFE_METHODS.has(request.method.toUpperCase())) {
+    const origin = request.headers.get("origin");
+    const site = request.headers.get("sec-fetch-site");
+    if (
+      (origin !== null && !isOriginOf(origin, host)) ||
+      (site !== null && site !== "same-origin" && site !== "none")
+    ) {
+      return refuse(403, "This console takes changes only from its own pages.");
+    }
+  }
+
+  const url = new URL(request.url);
+  const name = cookieName(port);
+  const given = url.searchParams.get(LOCAL_CONSOLE_SESSION_PARAM);
+  if (session && given !== null && sameSecret(given, session)) {
+    url.searchParams.delete(LOCAL_CONSOLE_SESSION_PARAM);
+    return new Response(null, {
+      status: 303,
+      headers: {
+        "cache-control": "no-store",
+        location: `${url.pathname}${url.search}${url.hash}`,
+        "set-cookie": `${name}=${session}; Path=/; HttpOnly; SameSite=Strict`,
+      },
+    });
+  }
+  const cookie = cookieOf(request, name);
+  if (session && cookie !== undefined && sameSecret(cookie, session)) {
+    return undefined;
+  }
+  return refuse(
+    401,
+    session
+      ? "Open this console with the link hot-updater console printed."
+      : "Start this console with hot-updater console, and open the link it prints.",
+  );
+};

package/src/lib/server/nativeBuildQr.ts

@@ -0,0 +1,73 @@
+import { isUUIDv7 } from "@hot-updater/protocol";
+
+import { nativeBuildDownloadPath } from "../native-builds";
+import { qrCodePath } from "../qr-code";
+
+/** The header that carries the download URL the QR code holds. */
+export const DOWNLOAD_URL_HEADER = "x-hot-updater-download-url";
+
+/** The route that serves the QR code, under the console's own path. */
+export const NATIVE_BUILD_QR_PATH = "/_hot-updater/native-builds/qr";
+
+/** The pixel size of one module, so the image is legible at its own size. */
+const MODULE_PX = 6;
+
+const refusal = (status: number, message: string) =>
+  new Response(message, {
+    status,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": "text/plain; charset=utf-8",
+    },
+  });
+
+/**
+ * The URL of a native build's console download, under the console path the
+ * QR request came to: the console answers it with a fresh storage URL on
+ * each request, so it never expires.
+ */
+export const nativeBuildDownloadUrl = (request: Request, id: string) => {
+  const url = new URL(request.url);
+  const base = url.pathname.endsWith(NATIVE_BUILD_QR_PATH)
+    ? url.pathname.slice(0, -NATIVE_BUILD_QR_PATH.length)
+    : "";
+  return `${url.origin}${base}${nativeBuildDownloadPath(id)}`;
+};
+
+/**
+ * The QR code of a native build's download URL, `<console>/api/native-builds/
+ * <id>/download`, as an SVG image, served at
+ * `/_hot-updater/native-builds/qr?build=<id>` without a session: a pull
+ * request comment shows it, and GitHub fetches a comment's images
+ * anonymously. It reads nothing, no database and no storage, so it says
+ * nothing about whether the build exists; the download itself asks for the
+ * session. The response's `x-hot-updater-download-url` header is the URL.
+ *
+ * - 400: `build` is missing or not a UUIDv7;
+ * - 405: a method other than GET or HEAD.
+ */
+export const serveNativeBuildQr = (request: Request): Response => {
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    const response = refusal(405, "Method Not Allowed");
+    response.headers.set("allow", "GET, HEAD");
+    return response;
+  }
+  const id = new URL(request.url).searchParams.get("build");
+  if (id === null || !isUUIDv7(id)) {
+    return refusal(400, "Pass ?build=<native build ID>.");
+  }
+  const downloadUrl = nativeBuildDownloadUrl(request, id);
+  const { size, path } = qrCodePath(downloadUrl);
+  const pixels = size * MODULE_PX;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${pixels}" height="${pixels}" viewBox="0 0 ${size} ${size}" shape-rendering="crispEdges"><rect fill="#fff" width="${size}" height="${size}"/><path fill="#000" d="${path}"/></svg>`;
+  return new Response(request.method === "HEAD" ? null : svg, {
+    headers: {
+      // The URL depends only on the build ID and the console's own address.
+      "cache-control": "public, max-age=86400",
+      "content-type": "image/svg+xml",
+      "content-security-policy": "default-src 'none'",
+      "x-content-type-options": "nosniff",
+      [DOWNLOAD_URL_HEADER]: downloadUrl,
+    },
+  });
+};

package/src/lib/server/nativeBuilds.ts

@@ -0,0 +1,288 @@
+import {
+  type CompiledReleaseCatalog,
+  type HotUpdaterCoreApi,
+  type KeysetInput,
+  type NativeBuildRow,
+  projectCompiledCatalog,
+  type StorageAdapter,
+} from "@hot-updater/plugin-core";
+import type { ReleaseCatalogDescriptor } from "@hot-updater/protocol";
+
+import {
+  nativeBuildCatalogScopeKey,
+  nativeBuildChannel,
+  nativeBuildScope,
+} from "../native-builds";
+
+export interface KeysetPageInput {
+  /** Rows older than this key: the next page. */
+  readonly before?: string;
+  /** Rows newer than this key: the previous page. */
+  readonly after?: string;
+  readonly limit: number;
+}
+
+export interface KeysetPage<T> {
+  /** Newest first. */
+  readonly data: readonly T[];
+  /** `before` of the next page, when there may be older rows. */
+  readonly next?: string;
+  /** `after` of the previous page, when there may be newer rows. */
+  readonly previous?: string;
+}
+
+/**
+ * One page newest first, from one keyset read: newest first for the next
+ * page, oldest first (then reversed) for the previous one. `next` is set
+ * for a full page, so the last page may lead to an empty one.
+ */
+async function keysetPage<T>(
+  read: (input: KeysetInput) => Promise<readonly T[]>,
+  keyOf: (row: T) => string,
+  { before, after, limit }: KeysetPageInput,
+): Promise<KeysetPage<T>> {
+  const data =
+    after === undefined
+      ? await read({
+          order: "desc",
+          limit,
+          ...(before === undefined ? {} : { after: before }),
+        })
+      : [...(await read({ order: "asc", after, limit }))].reverse();
+  const first = data[0];
+  const last = data.at(-1);
+  const full = data.length === limit;
+  return {
+    data,
+    ...(last !== undefined && (after !== undefined || full)
+      ? { next: keyOf(last) }
+      : {}),
+    ...(first !== undefined && (after === undefined ? before : full)
+      ? { previous: keyOf(first) }
+      : {}),
+  };
+}
+
+export interface NativeBuildListInput extends KeysetPageInput {
+  /** Only the builds that embed this channel ID. */
+  readonly channelId?: string;
+}
+
+export type NativeBuildListResult = KeysetPage<NativeBuildRow>;
+
+/**
+ * One page of native builds, newest first: one read of the registry's ID
+ * index, or of its channel index for one channel's builds.
+ */
+export function listNativeBuilds(
+  core: Pick<HotUpdaterCoreApi, "listNativeBuilds">,
+  { channelId, ...page }: NativeBuildListInput,
+): Promise<NativeBuildListResult> {
+  return keysetPage(
+    (input) =>
+      core.listNativeBuilds({
+        ...input,
+        ...(channelId === undefined ? {} : { channelId }),
+      }),
+    ({ id }) => id,
+    page,
+  );
+}
+
+/** A patch from a build's built-in bundle: the bundle it updates to, and its size. */
+export interface NativeBuildPatch {
+  readonly bundleId: string;
+  readonly byteSize: number;
+}
+
+export type NativeBuildPatchPage = KeysetPage<NativeBuildPatch>;
+
+/** How many patches one page of a build's patches lists. */
+export const NATIVE_BUILD_PATCH_PAGE_SIZE = 20;
+
+/**
+ * One page of the patches from a built-in bundle, newest target first: one
+ * read of the patches index. The patch rows carry what the page shows, so
+ * no bundle is read.
+ */
+export function listNativeBuildPatches(
+  core: Pick<HotUpdaterCoreApi, "listPatchesFromBase">,
+  minBundleId: string,
+  page: KeysetPageInput,
+): Promise<NativeBuildPatchPage> {
+  return keysetPage(
+    async (input) =>
+      (await core.listPatchesFromBase(minBundleId, input)).map(
+        ({ bundle_id, byte_size }) => ({
+          bundleId: bundle_id,
+          byteSize: byte_size,
+        }),
+      ),
+    ({ bundleId }) => bundleId,
+    page,
+  );
+}
+
+export interface NativeBuildDetail {
+  readonly build: NativeBuildRow;
+  /** The channel the build embeds. */
+  readonly channel: string;
+  /** The Release Catalog scope whose releases an install is offered. */
+  readonly catalogScopeKey: string;
+  /** How many bundles patch from the built-in bundle, or null when its row is gone. */
+  readonly builtInBundle: { readonly childCount: number } | null;
+  /**
+   * The newest build of the build's scope, which new deploys take their
+   * patch base from: this build, or the build that supersedes it.
+   */
+  readonly newestInScope: NativeBuildRow | null;
+  /**
+   * The releases the update check serves an install of this build now,
+   * newest first: the scope's catalog, at the build's app version, down to
+   * the built-in bundle the device floors at.
+   */
+  readonly servedNow: readonly ReleaseCatalogDescriptor[];
+  /** The newest page of patches from the built-in bundle. */
+  readonly patches: NativeBuildPatchPage;
+}
+
+/**
+ * Everything a native build's page shows, in five reads whatever the
+ * build: the build, then its built-in bundle, its scope's newest build, its
+ * scope's catalog, and one page of patches from it. Null for an unknown ID.
+ */
+export async function getNativeBuildDetail(
+  core: Pick<
+    HotUpdaterCoreApi,
+    | "getNativeBuild"
+    | "getBundle"
+    | "findNativeBuild"
+    | "getReleaseCatalogRow"
+    | "listPatchesFromBase"
+  >,
+  id: string,
+): Promise<NativeBuildDetail | null> {
+  const build = await core.getNativeBuild(id);
+  if (build === null) return null;
+  const catalogScopeKey = nativeBuildCatalogScopeKey(build);
+  const [builtIn, newestInScope, catalog, patches] = await Promise.all([
+    core.getBundle(build.min_bundle_id),
+    core.findNativeBuild(nativeBuildScope(build)),
+    core.getReleaseCatalogRow(catalogScopeKey),
+    listNativeBuildPatches(core, build.min_bundle_id, {
+      limit: NATIVE_BUILD_PATCH_PAGE_SIZE,
+    }),
+  ]);
+  const servedNow =
+    catalog === null || catalog.is_tombstone
+      ? []
+      : projectCompiledCatalog(
+          JSON.parse(catalog.payload) as CompiledReleaseCatalog,
+          build.app_version ?? undefined,
+        ).filter(
+          // The floor the device applies: a release older than the build's
+          // built-in bundle is older than what the binary ships.
+          ({ bundleId }) =>
+            bundleId !== null && bundleId >= build.min_bundle_id,
+        );
+  return {
+    build,
+    channel: nativeBuildChannel(build),
+    catalogScopeKey,
+    builtInBundle: builtIn === null ? null : { childCount: builtIn.childCount },
+    newestInScope,
+    servedNow,
+    patches,
+  };
+}
+
+const protocolOf = (storageUri: string) =>
+  new URL(storageUri).protocol.replace(":", "");
+
+/** The storage that holds `storageUri`, by its protocol. */
+const storageFor = (storage: StorageAdapter, storageUri: string) =>
+  storage.protocol === protocolOf(storageUri) ? storage : undefined;
+
+/** A public URL no storage owns, which is its own download URL. */
+const isPublicUrl = (storageUri: string) =>
+  ["http", "https"].includes(protocolOf(storageUri));
+
+/**
+ * The URL a phone downloads a native build's artifact from, without the
+ * console's sign-in: the storage's download URL, which may expire. Null
+ * when the storage gives none, or the build is gone.
+ */
+export async function resolveNativeBuildDownloadUrl(
+  id: string,
+  {
+    core,
+    storage,
+  }: {
+    readonly core: Pick<HotUpdaterCoreApi, "getNativeBuild">;
+    readonly storage: StorageAdapter;
+  },
+): Promise<string | null> {
+  const build = await core.getNativeBuild(id);
+  if (build === null) return null;
+  const storageUri = build.artifact_storage_uri;
+  const adapter = storageFor(storage, storageUri);
+  if (adapter?.getDownloadUrl !== undefined) {
+    return (await adapter.getDownloadUrl({ storageUri })).url;
+  }
+  return adapter === undefined && isPublicUrl(storageUri) ? storageUri : null;
+}
+
+/**
+ * Downloads a native build's artifact: a redirect to the storage's download
+ * URL, or the object streamed through the console when the storage gives
+ * no URL. The redirect is resolved on each request, so the console's link
+ * never expires.
+ */
+export async function downloadNativeBuild(
+  id: string,
+  {
+    core,
+    storage,
+  }: {
+    readonly core: Pick<HotUpdaterCoreApi, "getNativeBuild">;
+    readonly storage: StorageAdapter;
+  },
+): Promise<Response> {
+  const build = await core.getNativeBuild(id);
+  if (build === null) return new Response("Build not found", { status: 404 });
+
+  const storageUri = build.artifact_storage_uri;
+  const adapter = storageFor(storage, storageUri);
+  if (adapter?.getDownloadUrl !== undefined) {
+    const { url } = await adapter.getDownloadUrl({ storageUri });
+    return new Response(null, {
+      headers: { "cache-control": "private, no-store", location: url },
+      status: 302,
+    });
+  }
+  if (adapter?.get !== undefined) {
+    const { response } = await adapter.get({ storageUri });
+    if (!response) {
+      return new Response("Storage object not found", { status: 404 });
+    }
+    const fileName = decodeURIComponent(storageUri.split("/").at(-1) ?? "");
+    const headers = new Headers(response.headers);
+    headers.set("cache-control", "private, no-store");
+    headers.set(
+      "content-disposition",
+      `attachment; filename*=UTF-8''${encodeURIComponent(fileName)}`,
+    );
+    return new Response(response.body, {
+      headers,
+      status: response.status,
+      statusText: response.statusText,
+    });
+  }
+  if (adapter === undefined && isPublicUrl(storageUri)) {
+    return Response.redirect(storageUri, 302);
+  }
+  return new Response(
+    `No storage adapter for protocol: ${protocolOf(storageUri)}`,
+    { status: 503 },
+  );
+}

package/src/lib/shell.ts

@@ -0,0 +1,9 @@
+/**
+ * `value` as one POSIX shell word: as it is when it holds only characters
+ * no shell treats specially, else in single quotes, so a file name or link
+ * the Console shows in a command can't run anything when it is pasted.
+ */
+export const shellQuote = (value: string): string =>
+  /^[\w@%+=:,./-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", `'\\''`)}'`;