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

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

@@ -1,73 +0,0 @@
-import { definePlugin } from "../definePlugin";
-import {
-  API_KEY_HEADER_NAME,
-  authenticateApiKey,
-  createApiKeyManagement,
-  normalizeApiKeyHeaderName,
-  provisionApiKey,
-  registerApiKey,
-} from "./apiKeys";
-import { apiKeysCli } from "./cli";
-import { createApiKeyModel } from "./model";
-import { apiKeysSchema } from "./schema";
-
-export {
-  API_KEY_HEADER_NAME,
-  type ApiKeyManagementAPI,
-  type ApiKeyMetadata,
-  type CreatedApiKey,
-} from "./apiKeys";
-export { createApiKeyModel, type ApiKeyModel, type ApiKeyRow } 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;
-}
-
-/**
- * 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 definePlugin({
-    id: "apiKeys",
-    // Keeps its table's name, api_keys, and with it the camelCase id.
-    namespace: false,
-    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,
-            }),
-        },
-      };
-    },
-    cli: apiKeysCli(headerName),
-  });
-};

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

@@ -1,88 +0,0 @@
-import type { HotUpdaterDatabase } from "../../database/database";
-import { DatabaseConstraintError } from "../../database/errors";
-import type { ApiKeysSchema } from "./schema";
-
-export interface ApiKeyRow {
-  readonly id: string;
-  readonly hash: string;
-  readonly name: string;
-  readonly prefix: string;
-  readonly role: "client";
-  readonly created_at_ms: number;
-  readonly revoked_at_ms: number | null;
-}
-
-/** The api-keys plugin's storage: key rows by id and by hash. */
-export interface ApiKeyModel {
-  create(row: ApiKeyRow): Promise<"created" | "existing">;
-  findByHash(hash: string): Promise<ApiKeyRow | null>;
-  list(): Promise<readonly ApiKeyRow[]>;
-  revoke(input: {
-    readonly id: string;
-    readonly revokedAtMs: number;
-  }): Promise<ApiKeyRow | null>;
-}
-
-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

@@ -1,22 +0,0 @@
-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/definePlugin.ts

@@ -1,242 +0,0 @@
-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 a key or token check. */
-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";
-    };
-
-/** A positional argument of a plugin command. */
-export interface PluginCommandArgument {
-  /** The key of its value in `args`. */
-  readonly name: string;
-  readonly description: string;
-  /** Defaults to true. */
-  readonly required?: boolean;
-}
-
-/** An option of a plugin command. */
-export interface PluginCommandOption {
-  /** Flags as the CLI writes them, such as `--name <name>` or `-y, --yes`. */
-  readonly flags: string;
-  readonly description: string;
-  /** The command fails without it. */
-  readonly required?: boolean;
-}
-
-export interface PluginTableColumn<TKey extends string> {
-  readonly key: TKey;
-  readonly label?: string;
-  /** Styles the padded cell. */
-  readonly format?: (value: string) => string;
-}
-
-/**
- * The CLI's output style, so plugin commands read like core ones: the
- * formatters return styled text, and the writers print it.
- */
-export interface PluginCommandUi {
-  block(heading: string, lines: readonly string[]): string;
-  kv(label: string, value: string): string;
-  table<TKey extends string>(
-    columns: readonly PluginTableColumn<TKey>[],
-    rows: readonly Readonly<Record<TKey, string>>[],
-  ): string;
-  id(value: string): string;
-  muted(value: string): string;
-  success(value: string): string;
-  danger(value: string): string;
-  warning(value: string): string;
-  message(text: string): void;
-  info(text: string): void;
-  warn(text: string): void;
-  /** Writes machine-readable output, such as JSON, to stdout. */
-  print(text: string): void;
-  /**
-   * Returns once the user agrees to `message`. Declining ends the command,
-   * and a non-interactive shell fails it, asking for `-y`.
-   */
-  confirm(message: string): Promise<void>;
-}
-
-/** A plugin command run over a database the CLI opens itself. */
-export interface PluginCommandContext<Api = unknown> {
-  /** The plugin's API over that database, assembled as the server assembles it. */
-  readonly api: Api;
-  /** Positional arguments by name. */
-  readonly args: Readonly<Record<string, string | undefined>>;
-  /** Options by camel-cased long flag: `dryRun` for `--dry-run`. */
-  readonly options: Readonly<Record<string, unknown>>;
-  readonly ui: PluginCommandUi;
-}
-
-/**
- * A `hot-updater` command a plugin adds. It groups `commands`, or runs `run`
- * over a database the CLI opens itself, so it refuses a `standaloneRepository`
- * config. A command that runs also takes the server config's path as its
- * last, optional argument.
- */
-export interface PluginCommand<Api = unknown> {
-  /** Lowercase words joined by hyphens, such as `api-key`. */
-  readonly name: string;
-  readonly description: string;
-  readonly arguments?: readonly PluginCommandArgument[];
-  readonly options?: readonly PluginCommandOption[];
-  readonly commands?: readonly PluginCommand<Api>[];
-  run?(context: PluginCommandContext<Api>): Promise<void>;
-}
-
-/**
- * The credential an app sends to client routes that the plugin's clientAuth
- * guards. Init provisions it and prints the header to send, the agent
- * scaffold stores it, and doctor checks it.
- */
-export interface PluginClientCredential<Api = unknown> {
-  /** Its name in output, such as "API key". */
-  readonly label: string;
-  /** The request header that carries it, one of clientAuth's varyHeaders. */
-  readonly header: string;
-  /** The environment variable init stores it in. */
-  readonly env: string;
-  /** A new credential, made without a database, so tooling can save it before registering it. */
-  generate(): string;
-  /** Registers `existing` idempotently, or creates one; returns the credential. */
-  provision(
-    api: Api,
-    input: { readonly existing?: string; readonly name: string },
-  ): Promise<string>;
-}
-
-/**
- * A client plugin an app adds to `HotUpdater.init`'s `plugins` to work with
- * the server plugin. Init prints it in the app code, and the agent scaffold
- * asks for it.
- */
-export interface PluginClientPlugin {
-  /** The module that exports it, such as `@hot-updater/react-native/plugins/insights`. */
-  readonly module: string;
-  /** The export, which the app calls with no arguments, such as `insights`. */
-  readonly name: string;
-}
-
-/** What a plugin adds to the `hot-updater` CLI. */
-export interface PluginCli<Api = unknown> {
-  /** Commands the CLI finds in the project's plugins. */
-  readonly commands?: readonly PluginCommand<Api>[];
-  /** Needs provides: { clientAuth: true }. */
-  readonly clientCredential?: PluginClientCredential<Api>;
-  readonly clientPlugin?: PluginClientPlugin;
-}
-
-/** CLI additions whose `clientCredential` matches what the plugin declares it provides. */
-export type CliFor<TProvides, TApi> = TProvides extends {
-  readonly clientAuth: true;
-}
-  ? PluginCli<TApi>
-  : Omit<PluginCli<TApi>, "clientCredential"> & {
-      readonly clientCredential?: "Declare provides: { clientAuth: true } to add clientCredential";
-    };
-
-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;
-  /**
-   * `false` keeps the declared table names instead of prefixing them with
-   * the plugin's id. The plugin then owns collisions with core's tables and
-   * other plugins' tables, which startup checks for the plugins a server
-   * runs, and only such a plugin may take a camelCase id.
-   */
-  readonly namespace?: false;
-  /** Called once at startup, synchronously. */
-  init(context: PluginContext<TSchema>): TInstance;
-  /** Read by the CLI only; the server never runs it. */
-  readonly cli?: PluginCli<TInstance["api"]>;
-  /** Only core modules carry a kind. */
-  readonly kind?: "Core is built in; it is not a plugin";
-}
-
-/** Declares a plugin; Hot Updater's own plugins and third-party ones 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;
-  readonly namespace?: false;
-  init(context: PluginContext<TSchema>): InstanceFor<TProvides, TInstance>;
-  readonly cli?: CliFor<TProvides, NoInfer<TInstance["api"]>>;
-}): 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

@@ -1,73 +0,0 @@
-/**
- * The plugin authoring API. Hot Updater's own plugins and third-party ones
- * declare their tables and aggregates here and receive a typed database
- * handle in `init`.
- */
-export {
-  addDistinct,
-  countDistinct,
-  mergeDistinct,
-} from "@hot-updater/plugin-core/internal";
-export {
-  definePlugin,
-  type AnyHotUpdaterPlugin,
-  type CliFor,
-  type ClientAuth,
-  type CoreReader,
-  type HotUpdaterPlugin,
-  type InstanceFor,
-  type PluginApis,
-  type PluginCli,
-  type PluginClientCredential,
-  type PluginClientPlugin,
-  type PluginCommand,
-  type PluginCommandArgument,
-  type PluginCommandContext,
-  type PluginCommandOption,
-  type PluginCommandUi,
-  type PluginContext,
-  type PluginEndpoint,
-  type PluginEndpointMethod,
-  type PluginInstance,
-  type PluginProvides,
-  type PluginTableColumn,
-} from "./definePlugin";
-export {
-  defineAggregate,
-  defineTable,
-  type AggregateDefinition,
-  type DerivedDefinition,
-  type FieldDefinition,
-  type FieldReference,
-  type FieldType,
-  type IndexDefinition,
-  type ModuleSchema,
-  type ReferenceAction,
-  type RetentionDefinition,
-  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 { isDatabaseBusyError } from "../database/busy";
-export { DatabaseQueryError } from "../database/engineReads";
-export { DatabaseCursorError } from "../database/cursor";
-export { HotUpdaterConfigError } from "../assembly/assemblePlugins";