@hiai-gg/docsmint 0.4.7 → 0.4.8

package/backend/src/lib/api-key-encryption.ts

@@ -0,0 +1,66 @@
+const VERSION = "v1";
+const AAD = new TextEncoder().encode("hiai-docs:category-api-key:v1");
+
+function bytesToBase64(bytes: Uint8Array): string {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+
+function base64ToBytes(value: string): Uint8Array<ArrayBuffer> {
+	const binary = atob(value);
+	const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+	for (let index = 0; index < binary.length; index += 1) {
+		bytes[index] = binary.charCodeAt(index);
+	}
+	return bytes;
+}
+
+async function importEncryptionKey(secret: string): Promise<CryptoKey> {
+	if (secret.length < 32) {
+		throw new Error("API_KEY_ENCRYPTION_SECRET must be at least 32 characters");
+	}
+	const digest = await crypto.subtle.digest(
+		"SHA-256",
+		new TextEncoder().encode(secret),
+	);
+	return crypto.subtle.importKey("raw", digest, "AES-GCM", false, [
+		"encrypt",
+		"decrypt",
+	]);
+}
+
+export async function encryptApiKey(
+	rawKey: string,
+	secret: string,
+): Promise<string> {
+	const iv = crypto.getRandomValues(new Uint8Array(12));
+	const key = await importEncryptionKey(secret);
+	const ciphertext = await crypto.subtle.encrypt(
+		{ name: "AES-GCM", iv, additionalData: AAD },
+		key,
+		new TextEncoder().encode(rawKey),
+	);
+	return `${VERSION}.${bytesToBase64(iv)}.${bytesToBase64(new Uint8Array(ciphertext))}`;
+}
+
+export async function decryptApiKey(
+	payload: string,
+	secret: string,
+): Promise<string> {
+	const [version, encodedIv, encodedCiphertext] = payload.split(".");
+	if (version !== VERSION || !encodedIv || !encodedCiphertext) {
+		throw new Error("Unsupported encrypted API key payload");
+	}
+	const key = await importEncryptionKey(secret);
+	const plaintext = await crypto.subtle.decrypt(
+		{
+			name: "AES-GCM",
+			iv: base64ToBytes(encodedIv),
+			additionalData: AAD,
+		},
+		key,
+		base64ToBytes(encodedCiphertext),
+	);
+	return new TextDecoder().decode(plaintext);
+}

package/backend/src/lib/api-keys.ts

@@ -0,0 +1,243 @@
+import { apiKeys } from "@hiai-docs/db/schema";
+import {
+	adminTenantContext,
+	withTenant,
+	ZERO_UUID,
+} from "@hiai-docs/db/with-tenant";
+import { and, desc, eq } from "drizzle-orm";
+import { decryptApiKey, encryptApiKey } from "./api-key-encryption";
+
+const API_KEY_ADMIN_TENANT = adminTenantContext(ZERO_UUID);
+
+export const GLOBAL_API_SCOPE = "global";
+export const CATEGORY_API_PERMISSIONS = ["read", "edit", "write"] as const;
+export type CategoryApiPermission = (typeof CATEGORY_API_PERMISSIONS)[number];
+export type CategoryApiScope = `category:${string}:${CategoryApiPermission}`;
+export type ApiKeyScope = typeof GLOBAL_API_SCOPE | CategoryApiScope;
+
+const CATEGORY_SCOPE_PATTERN =
+	/^category:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}):(read|edit|write)$/;
+
+/** Reject unknown, malformed, and duplicate persisted scopes. */
+export function parseApiKeyScopes(value: unknown): ApiKeyScope[] | null {
+	if (!Array.isArray(value) || value.length === 0) return null;
+	const scopes: ApiKeyScope[] = [];
+	const seen = new Set<string>();
+	for (const candidate of value) {
+		if (typeof candidate !== "string" || seen.has(candidate)) return null;
+		if (
+			candidate !== GLOBAL_API_SCOPE &&
+			!CATEGORY_SCOPE_PATTERN.test(candidate)
+		) {
+			return null;
+		}
+		seen.add(candidate);
+		scopes.push(candidate as ApiKeyScope);
+	}
+	return scopes;
+}
+
+export function buildCategoryApiKeyScopes(
+	categoryId: string,
+	permissions: { read: boolean; edit: boolean; write: boolean },
+): ApiKeyScope[] {
+	return (["read", "edit", "write"] as const)
+		.filter((permission) => permissions[permission])
+		.map((permission) => `category:${categoryId}:${permission}` as ApiKeyScope);
+}
+
+export function categoryIdFromApiKeyScopes(
+	scopes: readonly string[],
+): string | null {
+	const parsed = parseApiKeyScopes(scopes);
+	if (!parsed) return null;
+	for (const scope of parsed) {
+		const match = CATEGORY_SCOPE_PATTERN.exec(scope);
+		if (match?.[1]) return match[1];
+	}
+	return null;
+}
+
+/**
+ * Hash a raw API key with SHA-256.
+ */
+function hashKey(key: string): string {
+	const hasher = new Bun.CryptoHasher("sha256");
+	hasher.update(key);
+	return hasher.digest("hex");
+}
+
+/**
+ * Create a new API key for a user.
+ *
+ * Returns the raw key (only time it is ever exposed), the prefix, and the DB id.
+ */
+export async function createApiKey(
+	ownerId: string,
+	name: string,
+	scopes: ApiKeyScope[],
+	expiresAt?: Date,
+	options?: { encryptionSecret?: string },
+): Promise<{ key: string; prefix: string; id: string }> {
+	const rawKey = crypto.randomUUID();
+	const keyHash = hashKey(rawKey);
+	const prefix = rawKey.slice(0, 8);
+	const encryptedKey = options?.encryptionSecret
+		? await encryptApiKey(rawKey, options.encryptionSecret)
+		: null;
+
+	const [row] = await withTenant({ userId: ownerId, role: "user" }, (tx) =>
+		tx
+			.insert(apiKeys)
+			.values({
+				ownerId,
+				name,
+				keyHash,
+				prefix,
+				scopes,
+				expiresAt: expiresAt ?? null,
+				encryptedKey,
+			})
+			.returning({ id: apiKeys.id }),
+	);
+
+	if (!row) {
+		throw new Error("Failed to create API key");
+	}
+
+	return { key: rawKey, prefix, id: row.id };
+}
+
+export async function revealCategoryApiKey(
+	id: string,
+	ownerId: string,
+	encryptionSecret: string,
+): Promise<string | null> {
+	const [row] = await withTenant({ userId: ownerId, role: "user" }, (tx) =>
+		tx
+			.select({
+				encryptedKey: apiKeys.encryptedKey,
+				scopes: apiKeys.scopes,
+			})
+			.from(apiKeys)
+			.where(and(eq(apiKeys.id, id), eq(apiKeys.ownerId, ownerId)))
+			.limit(1),
+	);
+	if (!row?.encryptedKey) return null;
+	const scopes = (row.scopes ?? []) as string[];
+	if (!categoryIdFromApiKeyScopes(scopes)) return null;
+	return decryptApiKey(row.encryptedKey, encryptionSecret);
+}
+
+/**
+ * List all API keys for a user (excludes the key hash).
+ */
+export async function listApiKeys(ownerId: string): Promise<
+	Array<{
+		id: string;
+		name: string;
+		prefix: string;
+		scopes: string[];
+		lastUsedAt: Date | null;
+		expiresAt: Date | null;
+		createdAt: Date;
+		recoverable: boolean;
+	}>
+> {
+	const rows = await withTenant({ userId: ownerId, role: "user" }, (tx) =>
+		tx
+			.select({
+				id: apiKeys.id,
+				name: apiKeys.name,
+				prefix: apiKeys.prefix,
+				scopes: apiKeys.scopes,
+				lastUsedAt: apiKeys.lastUsedAt,
+				expiresAt: apiKeys.expiresAt,
+				createdAt: apiKeys.createdAt,
+				encryptedKey: apiKeys.encryptedKey,
+			})
+			.from(apiKeys)
+			.where(eq(apiKeys.ownerId, ownerId))
+			.orderBy(desc(apiKeys.createdAt)),
+	);
+
+	return rows.map((r) => ({
+		id: r.id,
+		name: r.name,
+		prefix: r.prefix,
+		lastUsedAt: r.lastUsedAt,
+		expiresAt: r.expiresAt,
+		createdAt: r.createdAt,
+		recoverable: r.encryptedKey !== null,
+		scopes: (r.scopes ?? []) as string[],
+	}));
+}
+
+/**
+ * Revoke (delete) an API key by id and ownerId.
+ * Returns true if a key was deleted.
+ */
+export async function revokeApiKey(
+	id: string,
+	ownerId: string,
+): Promise<boolean> {
+	const deleted = await withTenant({ userId: ownerId, role: "user" }, (tx) =>
+		tx
+			.delete(apiKeys)
+			.where(and(eq(apiKeys.id, id), eq(apiKeys.ownerId, ownerId)))
+			.returning({ id: apiKeys.id }),
+	);
+
+	return deleted.length > 0;
+}
+
+/**
+ * Validate an API key.
+ * Returns { ownerId, scopes } if valid, or null if not found / expired.
+ * Updates lastUsedAt on successful validation.
+ */
+export async function validateApiKey(key: string): Promise<{
+	id: string;
+	ownerId: string;
+	scopes: ApiKeyScope[];
+} | null> {
+	const keyHash = hashKey(key);
+
+	const [row] = await withTenant(API_KEY_ADMIN_TENANT, (tx) =>
+		tx
+			.select({
+				id: apiKeys.id,
+				ownerId: apiKeys.ownerId,
+				scopes: apiKeys.scopes,
+				expiresAt: apiKeys.expiresAt,
+			})
+			.from(apiKeys)
+			.where(eq(apiKeys.keyHash, keyHash))
+			.limit(1),
+	);
+
+	if (!row) {
+		return null;
+	}
+
+	// Check expiration
+	if (row.expiresAt && new Date(row.expiresAt) < new Date()) {
+		return null;
+	}
+	const scopes = parseApiKeyScopes(row.scopes ?? []);
+	if (!scopes) return null;
+
+	// Update last_used_at
+	await withTenant(API_KEY_ADMIN_TENANT, (tx) =>
+		tx
+			.update(apiKeys)
+			.set({ lastUsedAt: new Date() })
+			.where(eq(apiKeys.id, row.id)),
+	);
+
+	return {
+		id: row.id,
+		ownerId: row.ownerId,
+		scopes,
+	};
+}

package/dist/backend/index.js

@@ -214361,7 +214361,7 @@ var swaggerConfig = {
   documentation: {
     info: {
       title: "DocsMint API",
-      version: "0.4.7",
+      version: "0.4.8",
       description: "Self-hosted AI-first documentation platform. Full-text + semantic search, version history, sharing, and folder organization.",
       contact: { name: "HiAi-gg", url: "https://github.com/HiAi-gg/docsmint" },
       license: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiai-gg/docsmint",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "type": "module",
   "browser": {
     "./dist/backend-launcher.js": false,
@@ -341,6 +341,8 @@
     "backend/src/lib/storage-factory.ts",
     "backend/src/lib/logger.ts",
     "backend/src/lib/api-key-facade.ts",
+    "backend/src/lib/api-keys.ts",
+    "backend/src/lib/api-key-encryption.ts",
     "backend/src/lib/lifecycle-service.ts",
     "README.md",
     "LICENSE"

package/packages/cli/src/index.ts

@@ -24,7 +24,7 @@ import { registerSearch } from "./commands/search.js";
 import { registerSnapshot } from "./commands/snapshot.js";
 import { registerUpdate } from "./commands/update.js";
 
-const VERSION = "0.4.7";
+const VERSION = "0.4.8";
 
 const program = new Command();
 program

package/packages/mcp-server/src/index.ts

@@ -35,7 +35,7 @@ interface McpToolResult {
 
 const server = new McpServer({
 	name: "hiai-docs",
-	version: "0.4.7",
+	version: "0.4.8",
 });
 
 /**