@hot-updater/plugin-api-keys 1.0.0-rc.20

package/dist/server/cli.mjs

@@ -0,0 +1,114 @@
+//#region src/server/cli.ts
+/** The environment variable init stores the app's API key in. */
+const API_KEY_ENV = "HOT_UPDATER_API_KEY";
+/** A new API key: 32 random bytes, base64url, as the plugin creates them. */
+const generateApiKey = () => {
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32));
+	return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+};
+const formatList = (ui, records) => 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`.
+*/
+const apiKeysCli = (headerName) => ({
+	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 === void 0 ? {} : { existingApiKey: existing },
+			name
+		})).apiKey
+	}
+});
+//#endregion
+export { API_KEY_ENV, apiKeysCli };

package/dist/server/index.cjs

@@ -0,0 +1,55 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_apiKeys = require("./apiKeys.cjs");
+const require_cli = require("./cli.cjs");
+const require_model = require("./model.cjs");
+const require_schema = require("./schema.cjs");
+let _hot_updater_plugin_core_internal = require("@hot-updater/plugin-core/internal");
+let _hot_updater_plugin_core_server_plugin = require("@hot-updater/plugin-core/server-plugin");
+//#region src/server/index.ts
+/**
+* API keys: protects client routes with keys whose SHA-256 digests
+* are stored, and manages them in-process.
+*/
+const apiKeys = (options = {}) => {
+	const headerName = require_apiKeys.normalizeApiKeyHeaderName(options.headerName ?? "x-api-key");
+	const plugin = (0, _hot_updater_plugin_core_server_plugin.definePlugin)({
+		id: "apiKeys",
+		namespace: false,
+		provides: { clientAuth: true },
+		schemaVersion: "1.0.0",
+		schema: require_schema.apiKeysSchema,
+		init: ({ db }) => {
+			const model = require_model.createApiKeyModel(db);
+			return {
+				api: {
+					...require_apiKeys.createApiKeyManagement({ apiKeys: model }),
+					/** Registers a known plaintext key idempotently, for managed init. */
+					register: (input) => require_apiKeys.registerApiKey({
+						...input,
+						apiKeys: model
+					}),
+					/** Reuses a saved key or creates one, for managed init. */
+					provision: (input) => require_apiKeys.provisionApiKey({
+						...input,
+						apiKeys: model
+					})
+				},
+				clientAuth: {
+					varyHeaders: [headerName],
+					authenticate: (headers) => require_apiKeys.authenticateApiKey({
+						apiKeys: model,
+						headerName,
+						request: { headers }
+					})
+				}
+			};
+		},
+		cli: require_cli.apiKeysCli(headerName)
+	});
+	return (0, _hot_updater_plugin_core_internal.markOfficial)(plugin);
+};
+//#endregion
+exports.API_KEY_HEADER_NAME = require_apiKeys.API_KEY_HEADER_NAME;
+exports.apiKeys = apiKeys;
+exports.apiKeysSchema = require_schema.apiKeysSchema;
+exports.createApiKeyModel = require_model.createApiKeyModel;

package/dist/server/index.d.cts

@@ -0,0 +1,81 @@
+import { ApiKeysSchema, apiKeysSchema } from "./schema.cjs";
+import { ApiKeyModel, ApiKeyRow, createApiKeyModel } from "./model.cjs";
+import { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey } from "./apiKeys.cjs";
+//#region src/server/index.d.ts
+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.
+ */
+declare const apiKeys: (options?: ApiKeysOptions) => import("@hot-updater/plugin-core/server-plugin").HotUpdaterPlugin<"apiKeys", {
+  readonly api_keys: import("@hot-updater/plugin-core/server-plugin").TableDefinition<{
+    readonly id: {
+      readonly type: "string";
+      readonly maxLength: 255;
+    };
+    readonly hash: {
+      readonly type: "string";
+      readonly maxLength: 64;
+      readonly unique: true;
+    };
+    readonly name: {
+      readonly type: "string";
+      readonly maxLength: 64;
+    };
+    readonly prefix: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly role: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly created_at_ms: {
+      readonly type: "integer";
+    };
+    readonly revoked_at_ms: {
+      readonly type: "integer";
+      readonly required: false;
+    };
+  }, {}, {
+    readonly byCreated: {
+      readonly eq: readonly [];
+      readonly sort: readonly ["created_at_ms"];
+    };
+  }, readonly ["id"]>;
+}, {
+  api: {
+    /** Registers a known plaintext key idempotently, for managed init. */
+    register: (input: {
+      readonly apiKey: string;
+      readonly name: string;
+      readonly createdAtMs?: number;
+    }) => Promise<CreatedApiKey>;
+    /** Reuses a saved key or creates one, for managed init. */
+    provision: (input: {
+      readonly existingApiKey?: string;
+      readonly name: string;
+    }) => Promise<CreatedApiKey>;
+    create(input: {
+      readonly name: string;
+    }): Promise<{
+      readonly apiKey: string;
+      readonly record: ApiKeyMetadata;
+    }>;
+    list(): Promise<readonly ApiKeyMetadata[]>;
+    revoke(input: {
+      readonly id: string;
+    }): Promise<ApiKeyMetadata | null>;
+  };
+  clientAuth: {
+    varyHeaders: string[];
+    authenticate: (headers: Headers) => Promise<boolean>;
+  };
+}, {
+  readonly clientAuth: true;
+}>;
+//#endregion
+export { API_KEY_HEADER_NAME, type ApiKeyManagementAPI, type ApiKeyMetadata, type ApiKeyModel, type ApiKeyRow, ApiKeysOptions, type ApiKeysSchema, type CreatedApiKey, apiKeys, apiKeysSchema, createApiKeyModel };

package/dist/server/index.d.mts

@@ -0,0 +1,81 @@
+import { ApiKeysSchema, apiKeysSchema } from "./schema.mjs";
+import { ApiKeyModel, ApiKeyRow, createApiKeyModel } from "./model.mjs";
+import { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey } from "./apiKeys.mjs";
+//#region src/server/index.d.ts
+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.
+ */
+declare const apiKeys: (options?: ApiKeysOptions) => import("@hot-updater/plugin-core/server-plugin").HotUpdaterPlugin<"apiKeys", {
+  readonly api_keys: import("@hot-updater/plugin-core/server-plugin").TableDefinition<{
+    readonly id: {
+      readonly type: "string";
+      readonly maxLength: 255;
+    };
+    readonly hash: {
+      readonly type: "string";
+      readonly maxLength: 64;
+      readonly unique: true;
+    };
+    readonly name: {
+      readonly type: "string";
+      readonly maxLength: 64;
+    };
+    readonly prefix: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly role: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly created_at_ms: {
+      readonly type: "integer";
+    };
+    readonly revoked_at_ms: {
+      readonly type: "integer";
+      readonly required: false;
+    };
+  }, {}, {
+    readonly byCreated: {
+      readonly eq: readonly [];
+      readonly sort: readonly ["created_at_ms"];
+    };
+  }, readonly ["id"]>;
+}, {
+  api: {
+    /** Registers a known plaintext key idempotently, for managed init. */
+    register: (input: {
+      readonly apiKey: string;
+      readonly name: string;
+      readonly createdAtMs?: number;
+    }) => Promise<CreatedApiKey>;
+    /** Reuses a saved key or creates one, for managed init. */
+    provision: (input: {
+      readonly existingApiKey?: string;
+      readonly name: string;
+    }) => Promise<CreatedApiKey>;
+    create(input: {
+      readonly name: string;
+    }): Promise<{
+      readonly apiKey: string;
+      readonly record: ApiKeyMetadata;
+    }>;
+    list(): Promise<readonly ApiKeyMetadata[]>;
+    revoke(input: {
+      readonly id: string;
+    }): Promise<ApiKeyMetadata | null>;
+  };
+  clientAuth: {
+    varyHeaders: string[];
+    authenticate: (headers: Headers) => Promise<boolean>;
+  };
+}, {
+  readonly clientAuth: true;
+}>;
+//#endregion
+export { API_KEY_HEADER_NAME, type ApiKeyManagementAPI, type ApiKeyMetadata, type ApiKeyModel, type ApiKeyRow, ApiKeysOptions, type ApiKeysSchema, type CreatedApiKey, apiKeys, apiKeysSchema, createApiKeyModel };

package/dist/server/index.mjs

@@ -0,0 +1,51 @@
+import { API_KEY_HEADER_NAME, authenticateApiKey, createApiKeyManagement, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey } from "./apiKeys.mjs";
+import { apiKeysCli } from "./cli.mjs";
+import { createApiKeyModel } from "./model.mjs";
+import { apiKeysSchema } from "./schema.mjs";
+import { markOfficial } from "@hot-updater/plugin-core/internal";
+import { definePlugin } from "@hot-updater/plugin-core/server-plugin";
+//#region src/server/index.ts
+/**
+* API keys: protects client routes with keys whose SHA-256 digests
+* are stored, and manages them in-process.
+*/
+const apiKeys = (options = {}) => {
+	const headerName = normalizeApiKeyHeaderName(options.headerName ?? "x-api-key");
+	const plugin = definePlugin({
+		id: "apiKeys",
+		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) => registerApiKey({
+						...input,
+						apiKeys: model
+					}),
+					/** Reuses a saved key or creates one, for managed init. */
+					provision: (input) => provisionApiKey({
+						...input,
+						apiKeys: model
+					})
+				},
+				clientAuth: {
+					varyHeaders: [headerName],
+					authenticate: (headers) => authenticateApiKey({
+						apiKeys: model,
+						headerName,
+						request: { headers }
+					})
+				}
+			};
+		},
+		cli: apiKeysCli(headerName)
+	});
+	return markOfficial(plugin);
+};
+//#endregion
+export { API_KEY_HEADER_NAME, apiKeys, apiKeysSchema, createApiKeyModel };

package/dist/server/model.cjs

@@ -0,0 +1,58 @@
+let _hot_updater_plugin_core_server_plugin = require("@hot-updater/plugin-core/server-plugin");
+//#region src/server/model.ts
+const toRow = (row) => ({
+	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
+});
+/** Today's `ApiKeyModel` on the engine: one unique read by hash, keyed writes. */
+const createApiKeyModel = (db) => ({
+	async create(row) {
+		try {
+			return await db.transaction(async (tx) => {
+				if (await tx.findOne("api_keys", { hash: row.hash }) !== null) return "existing";
+				tx.create("api_keys", row);
+				return "created";
+			});
+		} catch (error) {
+			if (error instanceof _hot_updater_plugin_core_server_plugin.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 = [];
+		let cursor;
+		do {
+			const page = await db.findMany("api_keys", {
+				index: "byCreated",
+				where: {},
+				order: "desc",
+				limit: 500,
+				...cursor === void 0 ? {} : { cursor }
+			});
+			rows.push(...page.rows.map(toRow));
+			cursor = page.next;
+		} while (cursor !== void 0);
+		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
+		});
+	})
+});
+//#endregion
+exports.createApiKeyModel = createApiKeyModel;

package/dist/server/model.d.cts

@@ -0,0 +1,26 @@
+import { ApiKeysSchema } from "./schema.cjs";
+import { HotUpdaterDatabase } from "@hot-updater/plugin-core/server-plugin";
+//#region src/server/model.d.ts
+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. */
+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>;
+}
+/** Today's `ApiKeyModel` on the engine: one unique read by hash, keyed writes. */
+declare const createApiKeyModel: (db: HotUpdaterDatabase<ApiKeysSchema>) => ApiKeyModel;
+//#endregion
+export { ApiKeyModel, ApiKeyRow, createApiKeyModel };

package/dist/server/model.d.mts

@@ -0,0 +1,26 @@
+import { ApiKeysSchema } from "./schema.mjs";
+import { HotUpdaterDatabase } from "@hot-updater/plugin-core/server-plugin";
+//#region src/server/model.d.ts
+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. */
+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>;
+}
+/** Today's `ApiKeyModel` on the engine: one unique read by hash, keyed writes. */
+declare const createApiKeyModel: (db: HotUpdaterDatabase<ApiKeysSchema>) => ApiKeyModel;
+//#endregion
+export { ApiKeyModel, ApiKeyRow, createApiKeyModel };

package/dist/server/model.mjs

@@ -0,0 +1,58 @@
+import { DatabaseConstraintError } from "@hot-updater/plugin-core/server-plugin";
+//#region src/server/model.ts
+const toRow = (row) => ({
+	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
+});
+/** Today's `ApiKeyModel` on the engine: one unique read by hash, keyed writes. */
+const createApiKeyModel = (db) => ({
+	async create(row) {
+		try {
+			return await db.transaction(async (tx) => {
+				if (await tx.findOne("api_keys", { hash: row.hash }) !== null) return "existing";
+				tx.create("api_keys", row);
+				return "created";
+			});
+		} 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 = [];
+		let cursor;
+		do {
+			const page = await db.findMany("api_keys", {
+				index: "byCreated",
+				where: {},
+				order: "desc",
+				limit: 500,
+				...cursor === void 0 ? {} : { cursor }
+			});
+			rows.push(...page.rows.map(toRow));
+			cursor = page.next;
+		} while (cursor !== void 0);
+		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
+		});
+	})
+});
+//#endregion
+export { createApiKeyModel };

package/dist/server/schema.cjs

@@ -0,0 +1,38 @@
+//#region src/server/schema.ts
+/** v1's `api_keys` columns; the plaintext key is never stored, only its SHA-256 digest. */
+const apiKeysSchema = { api_keys: (0, require("@hot-updater/plugin-core/server-plugin").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"]
+	} }
+}) };
+//#endregion
+exports.apiKeysSchema = apiKeysSchema;

package/dist/server/schema.d.cts

@@ -0,0 +1,42 @@
+//#region src/server/schema.d.ts
+/** v1's `api_keys` columns; the plaintext key is never stored, only its SHA-256 digest. */
+declare const apiKeysSchema: {
+  readonly api_keys: import("@hot-updater/plugin-core/server-plugin").TableDefinition<{
+    readonly id: {
+      readonly type: "string";
+      readonly maxLength: 255;
+    };
+    readonly hash: {
+      readonly type: "string";
+      readonly maxLength: 64;
+      readonly unique: true;
+    };
+    readonly name: {
+      readonly type: "string";
+      readonly maxLength: 64;
+    };
+    readonly prefix: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly role: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly created_at_ms: {
+      readonly type: "integer";
+    };
+    readonly revoked_at_ms: {
+      readonly type: "integer";
+      readonly required: false;
+    };
+  }, {}, {
+    readonly byCreated: {
+      readonly eq: readonly [];
+      readonly sort: readonly ["created_at_ms"];
+    };
+  }, readonly ["id"]>;
+};
+type ApiKeysSchema = typeof apiKeysSchema;
+//#endregion
+export { ApiKeysSchema, apiKeysSchema };

package/dist/server/schema.d.mts

@@ -0,0 +1,42 @@
+//#region src/server/schema.d.ts
+/** v1's `api_keys` columns; the plaintext key is never stored, only its SHA-256 digest. */
+declare const apiKeysSchema: {
+  readonly api_keys: import("@hot-updater/plugin-core/server-plugin").TableDefinition<{
+    readonly id: {
+      readonly type: "string";
+      readonly maxLength: 255;
+    };
+    readonly hash: {
+      readonly type: "string";
+      readonly maxLength: 64;
+      readonly unique: true;
+    };
+    readonly name: {
+      readonly type: "string";
+      readonly maxLength: 64;
+    };
+    readonly prefix: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly role: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly created_at_ms: {
+      readonly type: "integer";
+    };
+    readonly revoked_at_ms: {
+      readonly type: "integer";
+      readonly required: false;
+    };
+  }, {}, {
+    readonly byCreated: {
+      readonly eq: readonly [];
+      readonly sort: readonly ["created_at_ms"];
+    };
+  }, readonly ["id"]>;
+};
+type ApiKeysSchema = typeof apiKeysSchema;
+//#endregion
+export { ApiKeysSchema, apiKeysSchema };