@hot-updater/server 0.36.7 → 1.0.0-rc.0

package/dist/analytics/queryInput.cjs

@@ -0,0 +1,58 @@
+const require_errors = require("./errors.cjs");
+//#region src/analytics/queryInput.ts
+const EVENT_LIST_BOUNDS = {
+	defaultValue: 50,
+	maximum: 100,
+	minimum: 1
+};
+const EVENT_LIST_OFFSET_BOUNDS = {
+	defaultValue: 0,
+	minimum: 0
+};
+const MAX_USER_ID_LENGTH = 1024;
+function parseInteger(url, key, bounds) {
+	const value = url.searchParams.get(key);
+	if (value === null) return bounds.defaultValue;
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed < bounds.minimum || bounds.maximum !== void 0 && parsed > bounds.maximum) throw new require_errors.AnalyticsBadRequestError(`Invalid '${key}' query parameter.`);
+	return parsed;
+}
+const parsePagination = (request) => {
+	const url = new URL(request.url);
+	return {
+		limit: parseInteger(url, "limit", EVENT_LIST_BOUNDS),
+		offset: parseInteger(url, "offset", EVENT_LIST_OFFSET_BOUNDS)
+	};
+};
+const parseAnalyticsQuery = (request) => {
+	const window = new URL(request.url).searchParams.get("window") ?? "24h";
+	if (window !== "24h" && window !== "7d" && window !== "30d" && window !== "all") throw new require_errors.AnalyticsBadRequestError("Invalid 'window' query parameter.");
+	return {
+		...parsePagination(request),
+		window
+	};
+};
+const parseActiveInstallationInput = (request) => {
+	const url = new URL(request.url);
+	const windows = url.searchParams.getAll("window");
+	if (windows.length > 1) throw new require_errors.AnalyticsBadRequestError("Duplicate 'window' query parameter.");
+	const window = windows[0] ?? "30d";
+	if (window !== "24h" && window !== "7d" && window !== "30d") throw new require_errors.AnalyticsBadRequestError("Invalid 'window' query parameter.");
+	const userIds = url.searchParams.getAll("userId");
+	if (userIds.length > 1) throw new require_errors.AnalyticsBadRequestError("Duplicate 'userId' query parameter.");
+	const userId = userIds[0];
+	if (userId !== void 0 && (userId.length === 0 || userId.length > MAX_USER_ID_LENGTH)) throw new require_errors.AnalyticsBadRequestError("Invalid 'userId' query parameter.");
+	return userId === void 0 ? { window } : {
+		window,
+		userId
+	};
+};
+const parseSearchInput = (request) => ({
+	...parsePagination(request),
+	query: new URL(request.url).searchParams.get("query")?.trim() ?? ""
+});
+//#endregion
+exports.parseActiveInstallationInput = parseActiveInstallationInput;
+exports.parseAnalyticsQuery = parseAnalyticsQuery;
+exports.parsePagination = parsePagination;
+exports.parseSearchInput = parseSearchInput;

package/dist/analytics/queryInput.mjs

@@ -0,0 +1,55 @@
+import { AnalyticsBadRequestError } from "./errors.mjs";
+//#region src/analytics/queryInput.ts
+const EVENT_LIST_BOUNDS = {
+	defaultValue: 50,
+	maximum: 100,
+	minimum: 1
+};
+const EVENT_LIST_OFFSET_BOUNDS = {
+	defaultValue: 0,
+	minimum: 0
+};
+const MAX_USER_ID_LENGTH = 1024;
+function parseInteger(url, key, bounds) {
+	const value = url.searchParams.get(key);
+	if (value === null) return bounds.defaultValue;
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed < bounds.minimum || bounds.maximum !== void 0 && parsed > bounds.maximum) throw new AnalyticsBadRequestError(`Invalid '${key}' query parameter.`);
+	return parsed;
+}
+const parsePagination = (request) => {
+	const url = new URL(request.url);
+	return {
+		limit: parseInteger(url, "limit", EVENT_LIST_BOUNDS),
+		offset: parseInteger(url, "offset", EVENT_LIST_OFFSET_BOUNDS)
+	};
+};
+const parseAnalyticsQuery = (request) => {
+	const window = new URL(request.url).searchParams.get("window") ?? "24h";
+	if (window !== "24h" && window !== "7d" && window !== "30d" && window !== "all") throw new AnalyticsBadRequestError("Invalid 'window' query parameter.");
+	return {
+		...parsePagination(request),
+		window
+	};
+};
+const parseActiveInstallationInput = (request) => {
+	const url = new URL(request.url);
+	const windows = url.searchParams.getAll("window");
+	if (windows.length > 1) throw new AnalyticsBadRequestError("Duplicate 'window' query parameter.");
+	const window = windows[0] ?? "30d";
+	if (window !== "24h" && window !== "7d" && window !== "30d") throw new AnalyticsBadRequestError("Invalid 'window' query parameter.");
+	const userIds = url.searchParams.getAll("userId");
+	if (userIds.length > 1) throw new AnalyticsBadRequestError("Duplicate 'userId' query parameter.");
+	const userId = userIds[0];
+	if (userId !== void 0 && (userId.length === 0 || userId.length > MAX_USER_ID_LENGTH)) throw new AnalyticsBadRequestError("Invalid 'userId' query parameter.");
+	return userId === void 0 ? { window } : {
+		window,
+		userId
+	};
+};
+const parseSearchInput = (request) => ({
+	...parsePagination(request),
+	query: new URL(request.url).searchParams.get("query")?.trim() ?? ""
+});
+//#endregion
+export { parseActiveInstallationInput, parseAnalyticsQuery, parsePagination, parseSearchInput };

package/dist/analytics/routes.cjs

@@ -0,0 +1,63 @@
+const require_errors = require("./errors.cjs");
+const require_eventInput = require("./eventInput.cjs");
+const require_queryInput = require("./queryInput.cjs");
+//#region src/analytics/routes.ts
+const json = (body, status) => Response.json(body, {
+	headers: { "cache-control": "private, no-store" },
+	status
+});
+const requireParam = (params, key) => {
+	const value = params[key];
+	if (value === void 0 || value.length === 0) throw new require_errors.AnalyticsBadRequestError(`Missing route parameter: ${key}`);
+	return value;
+};
+const run = async (operation) => {
+	try {
+		return await operation();
+	} catch (error) {
+		if (error instanceof require_errors.AnalyticsBadRequestError) return json({ error: error.message }, 400);
+		if (error instanceof require_errors.AnalyticsPayloadTooLargeError) return json({ error: error.message }, 413);
+		if (error instanceof require_errors.AnalyticsScanLimitExceededError) return json({ error: {
+			code: "ANALYTICS_SCAN_LIMIT_EXCEEDED",
+			limit: error.limit
+		} }, 503);
+		throw error;
+	}
+};
+const query = (operation) => run(async () => json(await operation(), 200));
+const createAnalyticsRouteHandlers = (provider) => ({
+	appendBundleEvent: async (_params, request) => run(async () => {
+		await provider.appendBundleEvent(await require_eventInput.parseBundleEventRequest(request));
+		return new Response(null, { status: 204 });
+	}),
+	getBundleEventSummary: (params) => query(() => provider.getBundleEventSummary(requireParam(params, "id"))),
+	getBundleEventAnalytics: (params, request) => query(() => {
+		const input = require_queryInput.parseAnalyticsQuery(request);
+		return provider.getBundleEventAnalytics(requireParam(params, "id"), input.window, input.limit, input.offset);
+	}),
+	getBundleEventOverview: () => query(() => provider.getBundleEventOverview()),
+	getActiveInstallationOverview: (_params, request) => query(() => provider.getActiveInstallationOverview(require_queryInput.parseActiveInstallationInput(request))),
+	searchInstallations: (_params, request) => query(() => {
+		const input = require_queryInput.parseSearchInput(request);
+		return provider.searchInstallations(input.query, input.limit, input.offset);
+	}),
+	getInstallationHistory: (params, request) => query(() => {
+		const input = require_queryInput.parsePagination(request);
+		return provider.getInstallationHistory(requireParam(params, "installId"), input.limit, input.offset);
+	})
+});
+const registerAnalyticsClientRoutes = (add) => {
+	add("POST", "/events", "appendBundleEvent");
+};
+const registerAnalyticsAdminRoutes = (add) => {
+	add("GET", "/bundles/:id/events/summary", "getBundleEventSummary");
+	add("GET", "/bundles/:id/events/analytics", "getBundleEventAnalytics");
+	add("GET", "/installations/overview", "getBundleEventOverview");
+	add("GET", "/installations/active", "getActiveInstallationOverview");
+	add("GET", "/installations", "searchInstallations");
+	add("GET", "/installations/:installId/events", "getInstallationHistory");
+};
+//#endregion
+exports.createAnalyticsRouteHandlers = createAnalyticsRouteHandlers;
+exports.registerAnalyticsAdminRoutes = registerAnalyticsAdminRoutes;
+exports.registerAnalyticsClientRoutes = registerAnalyticsClientRoutes;

package/dist/analytics/routes.mjs

@@ -0,0 +1,61 @@
+import { AnalyticsBadRequestError, AnalyticsPayloadTooLargeError, AnalyticsScanLimitExceededError } from "./errors.mjs";
+import { parseBundleEventRequest } from "./eventInput.mjs";
+import { parseActiveInstallationInput, parseAnalyticsQuery, parsePagination, parseSearchInput } from "./queryInput.mjs";
+//#region src/analytics/routes.ts
+const json = (body, status) => Response.json(body, {
+	headers: { "cache-control": "private, no-store" },
+	status
+});
+const requireParam = (params, key) => {
+	const value = params[key];
+	if (value === void 0 || value.length === 0) throw new AnalyticsBadRequestError(`Missing route parameter: ${key}`);
+	return value;
+};
+const run = async (operation) => {
+	try {
+		return await operation();
+	} catch (error) {
+		if (error instanceof AnalyticsBadRequestError) return json({ error: error.message }, 400);
+		if (error instanceof AnalyticsPayloadTooLargeError) return json({ error: error.message }, 413);
+		if (error instanceof AnalyticsScanLimitExceededError) return json({ error: {
+			code: "ANALYTICS_SCAN_LIMIT_EXCEEDED",
+			limit: error.limit
+		} }, 503);
+		throw error;
+	}
+};
+const query = (operation) => run(async () => json(await operation(), 200));
+const createAnalyticsRouteHandlers = (provider) => ({
+	appendBundleEvent: async (_params, request) => run(async () => {
+		await provider.appendBundleEvent(await parseBundleEventRequest(request));
+		return new Response(null, { status: 204 });
+	}),
+	getBundleEventSummary: (params) => query(() => provider.getBundleEventSummary(requireParam(params, "id"))),
+	getBundleEventAnalytics: (params, request) => query(() => {
+		const input = parseAnalyticsQuery(request);
+		return provider.getBundleEventAnalytics(requireParam(params, "id"), input.window, input.limit, input.offset);
+	}),
+	getBundleEventOverview: () => query(() => provider.getBundleEventOverview()),
+	getActiveInstallationOverview: (_params, request) => query(() => provider.getActiveInstallationOverview(parseActiveInstallationInput(request))),
+	searchInstallations: (_params, request) => query(() => {
+		const input = parseSearchInput(request);
+		return provider.searchInstallations(input.query, input.limit, input.offset);
+	}),
+	getInstallationHistory: (params, request) => query(() => {
+		const input = parsePagination(request);
+		return provider.getInstallationHistory(requireParam(params, "installId"), input.limit, input.offset);
+	})
+});
+const registerAnalyticsClientRoutes = (add) => {
+	add("POST", "/events", "appendBundleEvent");
+};
+const registerAnalyticsAdminRoutes = (add) => {
+	add("GET", "/bundles/:id/events/summary", "getBundleEventSummary");
+	add("GET", "/bundles/:id/events/analytics", "getBundleEventAnalytics");
+	add("GET", "/installations/overview", "getBundleEventOverview");
+	add("GET", "/installations/active", "getActiveInstallationOverview");
+	add("GET", "/installations", "searchInstallations");
+	add("GET", "/installations/:installId/events", "getInstallationHistory");
+};
+//#endregion
+export { createAnalyticsRouteHandlers, registerAnalyticsAdminRoutes, registerAnalyticsClientRoutes };

package/dist/analytics/types.d.cts

@@ -0,0 +1,17 @@
+import { ActiveInstallationInput, ActiveInstallationOverview, BundleEventAnalyticsResult, BundleEventAnalyticsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, CreateBundleEventRequest, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult } from "./domain.cjs";
+
+//#region src/analytics/types.d.ts
+type AnalyticsProvider = {
+  readonly mode: "bounded";
+  readonly maxMatchingRows: number;
+  appendBundleEvent(input: CreateBundleEventRequest): Promise<void>;
+  getBundleEventSummary(bundleId: string): Promise<BundleEventSummary>;
+  getBundleEventSummaries(bundleIds: readonly string[], window: BundleEventAnalyticsWindow): Promise<readonly BundleEventSummaryByBundle[]>;
+  getBundleEventAnalytics(bundleId: string, window: BundleEventAnalyticsWindow, limit: number, offset: number): Promise<BundleEventAnalyticsResult>;
+  getBundleEventOverview(): Promise<BundleEventOverview>;
+  getActiveInstallationOverview(input: ActiveInstallationInput): Promise<ActiveInstallationOverview>;
+  searchInstallations(query: string, limit: number, offset: number): Promise<OffsetPaginationResult<InstallationSearchRow>>;
+  getInstallationHistory(installId: string, limit: number, offset: number): Promise<OffsetPaginationResult<InstallationHistoryRow>>;
+};
+//#endregion
+export { AnalyticsProvider };

package/dist/analytics/types.d.mts

@@ -0,0 +1,17 @@
+import { ActiveInstallationInput, ActiveInstallationOverview, BundleEventAnalyticsResult, BundleEventAnalyticsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, CreateBundleEventRequest, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult } from "./domain.mjs";
+
+//#region src/analytics/types.d.ts
+type AnalyticsProvider = {
+  readonly mode: "bounded";
+  readonly maxMatchingRows: number;
+  appendBundleEvent(input: CreateBundleEventRequest): Promise<void>;
+  getBundleEventSummary(bundleId: string): Promise<BundleEventSummary>;
+  getBundleEventSummaries(bundleIds: readonly string[], window: BundleEventAnalyticsWindow): Promise<readonly BundleEventSummaryByBundle[]>;
+  getBundleEventAnalytics(bundleId: string, window: BundleEventAnalyticsWindow, limit: number, offset: number): Promise<BundleEventAnalyticsResult>;
+  getBundleEventOverview(): Promise<BundleEventOverview>;
+  getActiveInstallationOverview(input: ActiveInstallationInput): Promise<ActiveInstallationOverview>;
+  searchInstallations(query: string, limit: number, offset: number): Promise<OffsetPaginationResult<InstallationSearchRow>>;
+  getInstallationHistory(installId: string, limit: number, offset: number): Promise<OffsetPaginationResult<InstallationHistoryRow>>;
+};
+//#endregion
+export { AnalyticsProvider };

package/dist/apiKeys.cjs

@@ -0,0 +1,139 @@
+//#region src/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("clientAccess.headerName must be a valid header name.");
+	try {
+		const headers = new Headers();
+		headers.set(value, "");
+		return headers.keys().next().value;
+	} catch {
+		throw new TypeError("clientAccess.headerName must be a valid header name.");
+	}
+};
+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 = 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 = 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);
+	await input.beforeLookup?.();
+	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 }) {
+		await input.beforeOperation();
+		const created = await createApiKey({
+			apiKeys: input.apiKeys,
+			name
+		});
+		return Object.freeze({
+			apiKey: created.apiKey,
+			record: created.record
+		});
+	},
+	async list() {
+		await input.beforeOperation();
+		return Object.freeze((await input.apiKeys.list()).map(toApiKeyMetadata));
+	},
+	async revoke({ id }) {
+		await input.beforeOperation();
+		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.authenticateApiKey = authenticateApiKey;
+exports.createApiKey = createApiKey;
+exports.createApiKeyManagement = createApiKeyManagement;
+exports.normalizeApiKeyHeaderName = normalizeApiKeyHeaderName;
+exports.provisionApiKey = provisionApiKey;
+exports.registerApiKey = registerApiKey;

package/dist/apiKeys.d.cts

@@ -0,0 +1,50 @@
+import { ApiKeyModel, ApiKeyRow } from "@hot-updater/plugin-core";
+
+//#region src/apiKeys.d.ts
+declare const API_KEY_HEADER_NAME = "x-api-key";
+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>;
+//#endregion
+export { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey, createApiKey, provisionApiKey, registerApiKey };

package/dist/apiKeys.d.mts

@@ -0,0 +1,50 @@
+import { ApiKeyModel, ApiKeyRow } from "@hot-updater/plugin-core";
+
+//#region src/apiKeys.d.ts
+declare const API_KEY_HEADER_NAME = "x-api-key";
+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>;
+//#endregion
+export { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey, createApiKey, provisionApiKey, registerApiKey };

package/dist/apiKeys.mjs

@@ -0,0 +1,133 @@
+//#region src/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("clientAccess.headerName must be a valid header name.");
+	try {
+		const headers = new Headers();
+		headers.set(value, "");
+		return headers.keys().next().value;
+	} catch {
+		throw new TypeError("clientAccess.headerName must be a valid header name.");
+	}
+};
+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 = 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 = 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);
+	await input.beforeLookup?.();
+	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 }) {
+		await input.beforeOperation();
+		const created = await createApiKey({
+			apiKeys: input.apiKeys,
+			name
+		});
+		return Object.freeze({
+			apiKey: created.apiKey,
+			record: created.record
+		});
+	},
+	async list() {
+		await input.beforeOperation();
+		return Object.freeze((await input.apiKeys.list()).map(toApiKeyMetadata));
+	},
+	async revoke({ id }) {
+		await input.beforeOperation();
+		const record = await input.apiKeys.revoke({
+			id,
+			revokedAtMs: Date.now()
+		});
+		return record === null ? null : toApiKeyMetadata(record);
+	}
+});
+//#endregion
+export { API_KEY_HEADER_NAME, authenticateApiKey, createApiKey, createApiKeyManagement, normalizeApiKeyHeaderName, provisionApiKey, registerApiKey };