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

package/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2023 Sungyu Kang 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+ADDITIONAL DISCLAIMER
+
+The authors of this software shall not be held responsible for any legal issues,
+regulatory violations, policy violations, or disputes arising from the use,
+distribution, or integration of this software.
+
+Users are solely responsible for ensuring compliance with all applicable laws,
+regulations, and third-party policies (including but not limited to app store
+policies).

package/README.md

@@ -0,0 +1,14 @@
+# @hot-updater/plugin-api-keys
+
+Hot Updater's API keys plugin. It protects the server's client routes with API
+keys, stores their SHA-256 digests, and adds `hot-updater api-key` commands to
+the CLI.
+
+You don't install it on its own. `@hot-updater/server` depends on it and
+re-exports its `./server` entry:
+
+```ts
+import { apiKeys } from "@hot-updater/server/plugins/api-keys";
+```
+
+See [API key authentication](https://hot-updater.dev/docs/custom/api-key-authentication).

package/dist/internal.cjs

@@ -0,0 +1,11 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_apiKeys = require("./server/apiKeys.cjs");
+const require_cli = require("./server/cli.cjs");
+exports.apiKeysCli = require_cli.apiKeysCli;
+exports.authenticateApiKey = require_apiKeys.authenticateApiKey;
+exports.createApiKey = require_apiKeys.createApiKey;
+exports.createApiKeyManagement = require_apiKeys.createApiKeyManagement;
+exports.hashApiKey = require_apiKeys.hashApiKey;
+exports.normalizeApiKeyHeaderName = require_apiKeys.normalizeApiKeyHeaderName;
+exports.provisionApiKey = require_apiKeys.provisionApiKey;
+exports.registerApiKey = require_apiKeys.registerApiKey;

package/dist/internal.d.cts

@@ -0,0 +1,3 @@
+import { authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey } from "./server/apiKeys.cjs";
+import { ApiKeysCliApi, apiKeysCli } from "./server/cli.cjs";
+export { type ApiKeysCliApi, apiKeysCli, authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey };

package/dist/internal.d.mts

@@ -0,0 +1,3 @@
+import { authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey } from "./server/apiKeys.mjs";
+import { ApiKeysCliApi, apiKeysCli } from "./server/cli.mjs";
+export { type ApiKeysCliApi, apiKeysCli, authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey };

package/dist/internal.mjs

@@ -0,0 +1,3 @@
+import { authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey } from "./server/apiKeys.mjs";
+import { apiKeysCli } from "./server/cli.mjs";
+export { apiKeysCli, authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey };

package/dist/server/apiKeys.cjs

@@ -0,0 +1,139 @@
+//#region src/server/apiKeys.ts
+const API_KEY_HEADER_NAME = "x-api-key";
+const BASE64URL_32_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
+const bytesToBase64Url = (bytes) => {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+};
+const isApiKey = (value) => {
+	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;
+	}
+};
+const normalizeApiKeyHeaderName = (value = API_KEY_HEADER_NAME) => {
+	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.");
+	}
+};
+const hashApiKey = async (apiKey) => {
+	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));
+};
+const apiKeyId = () => {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return `api-${bytesToBase64Url(bytes)}`;
+};
+const normalizeApiKeyName = (name) => {
+	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;
+};
+const toApiKeyMetadata = ({ hash: _hash, ...metadata }) => Object.freeze(metadata);
+const registerApiKey = async (input) => {
+	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"
+	});
+	if (await input.apiKeys.create(record) === "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)
+	});
+};
+const createApiKey = (input) => {
+	const bytes = /* @__PURE__ */ 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.
+*/
+const provisionApiKey = (input) => {
+	const existingApiKey = input.existingApiKey?.trim();
+	return existingApiKey ? registerApiKey({
+		apiKey: existingApiKey,
+		apiKeys: input.apiKeys,
+		name: input.name
+	}) : createApiKey({
+		apiKeys: input.apiKeys,
+		name: input.name
+	});
+};
+const authenticateApiKey = async (input) => {
+	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;
+};
+const createApiKeyManagement = (input) => Object.freeze({
+	async create({ name }) {
+		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 }) {
+		const record = await input.apiKeys.revoke({
+			id,
+			revokedAtMs: Date.now()
+		});
+		return record === null ? null : toApiKeyMetadata(record);
+	}
+});
+//#endregion
+exports.API_KEY_HEADER_NAME = API_KEY_HEADER_NAME;
+exports.apiKeyId = apiKeyId;
+exports.authenticateApiKey = authenticateApiKey;
+exports.createApiKey = createApiKey;
+exports.createApiKeyManagement = createApiKeyManagement;
+exports.hashApiKey = hashApiKey;
+exports.isApiKey = isApiKey;
+exports.normalizeApiKeyHeaderName = normalizeApiKeyHeaderName;
+exports.normalizeApiKeyName = normalizeApiKeyName;
+exports.provisionApiKey = provisionApiKey;
+exports.registerApiKey = registerApiKey;

package/dist/server/apiKeys.d.cts

@@ -0,0 +1,59 @@
+import { ApiKeyModel, ApiKeyRow } from "./model.cjs";
+//#region src/server/apiKeys.d.ts
+declare const API_KEY_HEADER_NAME = "x-api-key";
+declare const normalizeApiKeyHeaderName: (value?: unknown) => string;
+declare const hashApiKey: (apiKey: string) => Promise<string>;
+type ApiKeyMetadata = Omit<ApiKeyRow, "hash">;
+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;
+}
+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>;
+}
+declare const registerApiKey: (input: {
+  readonly apiKey: string;
+  readonly apiKeys: ApiKeyModel;
+  readonly createdAtMs?: number;
+  readonly name: string;
+}) => Promise<CreatedApiKey>;
+declare const createApiKey: (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly name: string;
+}) => Promise<CreatedApiKey>;
+/**
+ * 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.
+ */
+declare const provisionApiKey: (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly existingApiKey?: string;
+  readonly name: string;
+}) => Promise<CreatedApiKey>;
+declare const authenticateApiKey: (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly headerName?: string;
+  readonly request: Request;
+}) => Promise<boolean>;
+declare const createApiKeyManagement: (input: {
+  readonly apiKeys: ApiKeyModel;
+}) => ApiKeyManagementAPI;
+//#endregion
+export { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey, authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey };

package/dist/server/apiKeys.d.mts

@@ -0,0 +1,59 @@
+import { ApiKeyModel, ApiKeyRow } from "./model.mjs";
+//#region src/server/apiKeys.d.ts
+declare const API_KEY_HEADER_NAME = "x-api-key";
+declare const normalizeApiKeyHeaderName: (value?: unknown) => string;
+declare const hashApiKey: (apiKey: string) => Promise<string>;
+type ApiKeyMetadata = Omit<ApiKeyRow, "hash">;
+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;
+}
+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>;
+}
+declare const registerApiKey: (input: {
+  readonly apiKey: string;
+  readonly apiKeys: ApiKeyModel;
+  readonly createdAtMs?: number;
+  readonly name: string;
+}) => Promise<CreatedApiKey>;
+declare const createApiKey: (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly name: string;
+}) => Promise<CreatedApiKey>;
+/**
+ * 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.
+ */
+declare const provisionApiKey: (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly existingApiKey?: string;
+  readonly name: string;
+}) => Promise<CreatedApiKey>;
+declare const authenticateApiKey: (input: {
+  readonly apiKeys: ApiKeyModel;
+  readonly headerName?: string;
+  readonly request: Request;
+}) => Promise<boolean>;
+declare const createApiKeyManagement: (input: {
+  readonly apiKeys: ApiKeyModel;
+}) => ApiKeyManagementAPI;
+//#endregion
+export { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey, authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey };

package/dist/server/apiKeys.mjs

@@ -0,0 +1,129 @@
+//#region src/server/apiKeys.ts
+const API_KEY_HEADER_NAME = "x-api-key";
+const BASE64URL_32_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
+const bytesToBase64Url = (bytes) => {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+};
+const isApiKey = (value) => {
+	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;
+	}
+};
+const normalizeApiKeyHeaderName = (value = API_KEY_HEADER_NAME) => {
+	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.");
+	}
+};
+const hashApiKey = async (apiKey) => {
+	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));
+};
+const apiKeyId = () => {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return `api-${bytesToBase64Url(bytes)}`;
+};
+const normalizeApiKeyName = (name) => {
+	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;
+};
+const toApiKeyMetadata = ({ hash: _hash, ...metadata }) => Object.freeze(metadata);
+const registerApiKey = async (input) => {
+	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"
+	});
+	if (await input.apiKeys.create(record) === "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)
+	});
+};
+const createApiKey = (input) => {
+	const bytes = /* @__PURE__ */ 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.
+*/
+const provisionApiKey = (input) => {
+	const existingApiKey = input.existingApiKey?.trim();
+	return existingApiKey ? registerApiKey({
+		apiKey: existingApiKey,
+		apiKeys: input.apiKeys,
+		name: input.name
+	}) : createApiKey({
+		apiKeys: input.apiKeys,
+		name: input.name
+	});
+};
+const authenticateApiKey = async (input) => {
+	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;
+};
+const createApiKeyManagement = (input) => Object.freeze({
+	async create({ name }) {
+		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 }) {
+		const record = await input.apiKeys.revoke({
+			id,
+			revokedAtMs: Date.now()
+		});
+		return record === null ? null : toApiKeyMetadata(record);
+	}
+});
+//#endregion
+export { API_KEY_HEADER_NAME, apiKeyId, authenticateApiKey, createApiKey, createApiKeyManagement, hashApiKey, isApiKey, normalizeApiKeyHeaderName, normalizeApiKeyName, provisionApiKey, registerApiKey };

package/dist/server/cli.cjs

@@ -0,0 +1,115 @@
+//#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
+exports.API_KEY_ENV = API_KEY_ENV;
+exports.apiKeysCli = apiKeysCli;

package/dist/server/cli.d.cts

@@ -0,0 +1,17 @@
+import { ApiKeyManagementAPI, CreatedApiKey } from "./apiKeys.cjs";
+import { PluginCli } from "@hot-updater/plugin-core/server-plugin";
+//#region src/server/cli.d.ts
+/** The part of the apiKeys() API the CLI uses. */
+interface ApiKeysCliApi extends ApiKeyManagementAPI {
+  provision(input: {
+    readonly existingApiKey?: string;
+    readonly name: string;
+  }): Promise<CreatedApiKey>;
+}
+/**
+ * `hot-updater api-key create|list|revoke`, and the API key that init
+ * provisions for an app, sent in `headerName`.
+ */
+declare const apiKeysCli: (headerName: string) => PluginCli<ApiKeysCliApi>;
+//#endregion
+export { ApiKeysCliApi, apiKeysCli };

package/dist/server/cli.d.mts

@@ -0,0 +1,17 @@
+import { ApiKeyManagementAPI, CreatedApiKey } from "./apiKeys.mjs";
+import { PluginCli } from "@hot-updater/plugin-core/server-plugin";
+//#region src/server/cli.d.ts
+/** The part of the apiKeys() API the CLI uses. */
+interface ApiKeysCliApi extends ApiKeyManagementAPI {
+  provision(input: {
+    readonly existingApiKey?: string;
+    readonly name: string;
+  }): Promise<CreatedApiKey>;
+}
+/**
+ * `hot-updater api-key create|list|revoke`, and the API key that init
+ * provisions for an app, sent in `headerName`.
+ */
+declare const apiKeysCli: (headerName: string) => PluginCli<ApiKeysCliApi>;
+//#endregion
+export { ApiKeysCliApi, apiKeysCli };