@hiai-gg/hiai-docs 0.0.1

package/backend/src/embedding/providers/openrouter.ts

@@ -0,0 +1,71 @@
+/**
+ * OpenRouter embedding provider.
+ * POST to https://openrouter.ai/api/v1/embeddings using OPENROUTER_API_KEY.
+ */
+
+import { logger } from "../../lib/logger";
+import { normalizeDimensions } from "../utils";
+
+const EMBEDDING_DIMENSIONS = 1024;
+const TIMEOUT_MS = 30_000;
+const OPENROUTER_URL = "https://openrouter.ai/api/v1/embeddings";
+
+interface OpenRouterEmbeddingResponse {
+	data: Array<{ embedding: number[] }>;
+}
+
+/**
+ * Get an embedding vector from OpenRouter.
+ * @param text - Text to embed
+ * @param model - Model name (default: openai/text-embedding-3-small)
+ * @param apiKey - OpenRouter API key
+ * @returns number[] of length 1024
+ */
+export async function getOpenRouterEmbedding(
+	text: string,
+	model: string,
+	apiKey: string,
+): Promise<number[]> {
+	if (!apiKey) {
+		throw new Error("OPENROUTER_API_KEY is required for OpenRouter embeddings");
+	}
+
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+	try {
+		const response = await fetch(OPENROUTER_URL, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${apiKey}`,
+			},
+			body: JSON.stringify({ model, input: text }),
+			signal: controller.signal,
+		});
+
+		if (!response.ok) {
+			const body = await response.text().catch(() => "unknown");
+			throw new Error(
+				`OpenRouter embedding failed: ${response.status} ${body}`,
+			);
+		}
+
+		const data = (await response.json()) as OpenRouterEmbeddingResponse;
+		const embedding = data.data?.[0]?.embedding;
+
+		if (!Array.isArray(embedding) || embedding.length === 0) {
+			throw new Error("OpenRouter returned empty or invalid embedding");
+		}
+
+		return normalizeDimensions(embedding, EMBEDDING_DIMENSIONS);
+	} catch (err) {
+		if (err instanceof Error && err.name === "AbortError") {
+			logger.error({ model }, "OpenRouter embedding request timed out");
+			throw new Error(`OpenRouter embedding timed out after ${TIMEOUT_MS}ms`);
+		}
+		throw err;
+	} finally {
+		clearTimeout(timeout);
+	}
+}

package/backend/src/embedding/utils.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared embedding utilities.
+ */
+
+/**
+ * Pad or truncate a vector to exactly `dims` dimensions.
+ */
+export function normalizeDimensions(vec: number[], dims: number): number[] {
+	if (vec.length === dims) return vec;
+	if (vec.length > dims) return vec.slice(0, dims);
+	// Pad with zeros
+	return [...vec, ...new Array(dims - vec.length).fill(0)];
+}

package/backend/src/embedding/worker.ts

@@ -0,0 +1,89 @@
+import { documentEmbeddings, documents } from "@hiai-docs/db/schema";
+import { eq } from "drizzle-orm";
+import { db } from "../lib/db";
+import { logger } from "../lib/logger";
+import { redis } from "../lib/redis";
+import { embedDocument } from "./index";
+
+const QUEUE_KEY = "hiai-docs:embedding-queue";
+
+export function startEmbeddingWorker(): void {
+	logger.info("Embedding worker started");
+
+	const processLoop = async (): Promise<void> => {
+		while (true) {
+			try {
+				const result = await redis.brpop(QUEUE_KEY, 1);
+				if (!result) continue;
+				const documentId = result[1];
+				await processDocument(documentId);
+			} catch (err) {
+				logger.error({ err }, "Embedding worker error");
+			}
+		}
+	};
+
+	processLoop();
+}
+
+async function processDocument(documentId: string): Promise<void> {
+	logger.info({ documentId }, "Processing embedding for document");
+
+	try {
+		const doc = await db.query.documents.findFirst({
+			where: eq(documents.id, documentId),
+			columns: {
+				id: true,
+				title: true,
+				content: true,
+			},
+		});
+
+		if (!doc) {
+			logger.warn({ documentId }, "Document not found, skipping embedding");
+			return;
+		}
+
+		const content = doc.content ?? "";
+		if (!content && doc.title === "Untitled") {
+			logger.debug(
+				{ documentId },
+				"Document has no content, skipping embedding",
+			);
+			return;
+		}
+
+		const embeddings = await embedDocument(doc.title, content);
+
+		if (embeddings.length === 0) {
+			logger.warn({ documentId }, "No embeddings produced for document");
+			return;
+		}
+
+		await db.transaction(async (tx) => {
+			await tx
+				.delete(documentEmbeddings)
+				.where(eq(documentEmbeddings.documentId, documentId));
+
+			const rows = embeddings.map((embedding, index) => ({
+				documentId,
+				chunkIndex: index,
+				chunkText: "",
+				embedding,
+			}));
+
+			await tx.insert(documentEmbeddings).values(rows);
+		});
+
+		logger.info(
+			{
+				documentId,
+				chunks: embeddings.length,
+				dimensions: embeddings[0]?.length,
+			},
+			"All chunk embeddings stored for document",
+		);
+	} catch (err) {
+		logger.error({ err, documentId }, "Failed to process document embedding");
+	}
+}

package/backend/src/index.ts

@@ -0,0 +1,147 @@
+import { cors } from "@elysiajs/cors";
+import { swagger } from "@elysiajs/swagger";
+import { Elysia } from "elysia";
+import { authMiddleware } from "./api/middleware/auth";
+import { csrfMiddleware } from "./api/middleware/csrf";
+import {
+	healthRateLimiter,
+	rateLimitHeaders,
+} from "./api/middleware/rate-limit";
+import { attachmentRoutes } from "./api/routes/attachments";
+import { authRoutes } from "./api/routes/auth";
+import { collaborationRoutes } from "./api/routes/collaboration";
+import { documentRoutes } from "./api/routes/documents";
+import { folderRoutes } from "./api/routes/folders";
+import { searchRoutes } from "./api/routes/search";
+import { shareRoutes } from "./api/routes/share";
+import { tagRoutes } from "./api/routes/tags";
+import { versionRoutes } from "./api/routes/versions";
+import { webhookRoutes } from "./api/routes/webhooks";
+import { config } from "./lib/config";
+import { startEmbeddingWorker } from "./lib/embedding-queue";
+import { logger } from "./lib/logger";
+import { BUCKET, ensureBucket, minio } from "./lib/minio";
+
+// Start background embedding worker
+startEmbeddingWorker();
+
+ensureBucket(minio, BUCKET).catch((err) => {
+	logger.error({ err }, "Failed to ensure MinIO bucket");
+});
+
+const MAX_BODY_SIZE_BYTES = 10 * 1024 * 1024;
+
+const CSP_POLICY = [
+	"default-src 'self'",
+	"script-src 'self' 'unsafe-inline'",
+	"style-src 'self' 'unsafe-inline'",
+	"img-src 'self' data: blob: http://localhost:9020 http://localhost:9000 http://minio:9000",
+	"connect-src 'self' http://localhost:50700 ws://localhost:50700",
+	"font-src 'self' data:",
+	"frame-ancestors 'none'",
+	"form-action 'self'",
+].join("; ");
+
+const HSTS_POLICY = "max-age=31536000; includeSubDomains";
+
+const bodySizeLimit = new Elysia().onBeforeHandle(({ request, set }) => {
+	const contentLength = request.headers.get("content-length");
+	if (contentLength !== null) {
+		const length = Number(contentLength);
+		if (Number.isFinite(length) && length > MAX_BODY_SIZE_BYTES) {
+			set.status = 413;
+			set.headers["X-Content-Type-Options"] = "nosniff";
+			set.headers["X-Frame-Options"] = "DENY";
+			return { error: "Request body too large (max 10MB)" };
+		}
+	}
+});
+
+const securityHeaders = new Elysia().onAfterHandle(({ set }) => {
+	set.headers["Content-Security-Policy"] = CSP_POLICY;
+	set.headers["Strict-Transport-Security"] = HSTS_POLICY;
+	set.headers["X-Content-Type-Options"] = "nosniff";
+	set.headers["X-Frame-Options"] = "DENY";
+});
+
+const swaggerConfig = {
+	path: "/api/docs",
+	documentation: {
+		info: {
+			title: "hiai-docs API",
+			version: "0.1.0",
+			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/hiai-docs" },
+			license: { name: "MIT", url: "https://opensource.org/licenses/MIT" },
+		},
+		tags: [
+			{ name: "Auth", description: "Authentication endpoints" },
+			{ name: "Documents", description: "Document CRUD and search" },
+			{ name: "Folders", description: "Folder management" },
+			{ name: "Tags", description: "Tag management" },
+			{ name: "Versions", description: "Document version history" },
+			{ name: "Share", description: "Sharing and guest access" },
+			{ name: "Search", description: "Hybrid full-text + semantic search" },
+		],
+	},
+};
+
+const app = new Elysia()
+	.use(bodySizeLimit)
+	.use(securityHeaders)
+	.use(
+		cors({
+			origin: config.CORS_ORIGINS?.split(",") ?? [config.BETTER_AUTH_URL],
+			credentials: true,
+			maxAge: 86400,
+		}),
+	)
+	.use(
+		config.NODE_ENV !== "production"
+			? swagger(swaggerConfig)
+			: (e: Elysia) => e,
+	)
+	.get("/api/health", async ({ request }) => {
+		const ip =
+			request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+			request.headers.get("x-real-ip") ??
+			"unknown";
+		const rl = await healthRateLimiter(ip);
+		const headers = rateLimitHeaders(rl.remaining, rl.retryAfter);
+		return Object.assign(
+			{
+				status: "ok",
+				service: "hiai-docs",
+				timestamp: new Date().toISOString(),
+			},
+			headers,
+		);
+	})
+	.use(csrfMiddleware)
+	.use(authMiddleware)
+	.use(authRoutes)
+	.use(tagRoutes)
+	.use(attachmentRoutes)
+	.use(shareRoutes)
+	.use(searchRoutes)
+	.use(documentRoutes)
+	.use(folderRoutes)
+	.use(versionRoutes)
+	.use(webhookRoutes)
+	.use(collaborationRoutes)
+	.listen(config.API_PORT);
+
+logger.info({ port: config.API_PORT }, "hiai-docs API started");
+
+// Graceful shutdown
+const shutdown = async () => {
+	logger.info("Shutting down...");
+	app.stop();
+	process.exit(0);
+};
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
+export type App = typeof app;

package/backend/src/lib/auth-helpers.ts

@@ -0,0 +1,27 @@
+import { auth } from "./auth";
+import { config } from "./config";
+
+/**
+ * Extract user ID from request headers.
+ * Checks API key first (Bearer token), then falls back to Better Auth session.
+ * Returns null if no valid session.
+ */
+export async function getSessionUserId(
+	headers: Headers,
+): Promise<string | null> {
+	// Check API key first
+	const apiKey = config.HIAI_DOCS_API_KEY;
+	if (apiKey) {
+		const authHeader = headers.get("authorization");
+		if (authHeader?.startsWith("Bearer ")) {
+			const token = authHeader.slice(7);
+			if (token === apiKey) {
+				return config.OWNER_ID;
+			}
+		}
+	}
+
+	// Fall back to Better Auth session check
+	const session = await auth.api.getSession({ headers });
+	return session?.user?.id ?? null;
+}

package/backend/src/lib/auth.ts

@@ -0,0 +1,35 @@
+import { db } from "@hiai-docs/db";
+import { accounts, sessions, users, verifications } from "@hiai-docs/db/schema";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { config } from "./config";
+
+export const auth = betterAuth({
+	database: drizzleAdapter(db, {
+		provider: "pg",
+		schema: {
+			user: users,
+			session: sessions,
+			account: accounts,
+			verification: verifications,
+		},
+	}),
+	secret: config.BETTER_AUTH_SECRET,
+	baseURL: config.BETTER_AUTH_URL,
+	trustedOrigins: process.env.TRUSTED_ORIGINS
+		? process.env.TRUSTED_ORIGINS.split(",").map((s) => s.trim())
+		: ["http://localhost:50701", "http://127.0.0.1:50701"],
+	emailAndPassword: {
+		enabled: true,
+	},
+	session: {
+		expiresIn: 60 * 60 * 24 * 7, // 7 days
+		updateAge: 60 * 60 * 24, // 1 day
+	},
+	advanced: {
+		database: {
+			generateId: false,
+		},
+		disableCSRFCheck: true,
+	},
+});

package/backend/src/lib/config.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { logger } from "./logger";
+
+const envSchema = z.object({
+	DATABASE_URL: z
+		.string()
+		.default("postgresql://aiuser:aipassword@localhost:5433/hiai_docs"),
+	REDIS_URL: z.string().default("redis://localhost:6380"),
+	MINIO_ENDPOINT: z.string().default("localhost"),
+	MINIO_PORT: z.coerce.number().default(9010),
+	MINIO_PUBLIC_ENDPOINT: z.string().default("localhost"),
+	MINIO_PUBLIC_PORT: z.coerce.number().default(9020),
+	MINIO_ACCESS_KEY: z.string().default("minioadmin"),
+	MINIO_SECRET_KEY: z.string().default("change-me-to-random-32-chars"),
+	MINIO_BUCKET: z.string().default("hiai-docs"),
+	BETTER_AUTH_SECRET: z
+		.string()
+		.default("change-me-to-random-32-chars")
+		.refine(
+			(val) =>
+				process.env.NODE_ENV !== "production" ||
+				val !== "change-me-to-random-32-chars",
+			"BETTER_AUTH_SECRET must be set in production",
+		),
+	// CSRF: dedicated signing key — must NOT equal BETTER_AUTH_SECRET
+	CSRF_SECRET: z.string().default("change-me-to-random-32-chars"),
+	// Webhook: dedicated HMAC key — must NOT equal MINIO_SECRET_KEY
+	WEBHOOK_SECRET: z.string().default("change-me-to-random-32-chars"),
+	BETTER_AUTH_URL: z.string().default("http://localhost:50700"),
+	CORS_ORIGINS: z.string().optional(),
+	EMBEDDING_PROVIDER: z
+		.enum(["ollama", "openrouter", "voyage"])
+		.default("ollama"),
+	EMBEDDING_MODEL: z.string().default("nomic-embed-text"),
+	EMBEDDING_OLLAMA_URL: z.string().default("http://localhost:11434"),
+	EMBEDDING_FALLBACK_PROVIDER: z.string().default("openrouter"),
+	EMBEDDING_FALLBACK_MODEL: z.string().default("openai/text-embedding-3-small"),
+	OPENROUTER_API_KEY: z.string().optional(),
+	API_PORT: z.coerce.number().default(50700),
+	NODE_ENV: z
+		.enum(["development", "production", "test"])
+		.default("development"),
+	LOG_LEVEL: z
+		.enum(["trace", "debug", "info", "warn", "error", "fatal"])
+		.default("info"),
+	HIAI_DOCS_API_KEY: z.string().optional(),
+	OWNER_ID: z.string().default("api-key-user"),
+});
+
+let config: z.infer<typeof envSchema>;
+try {
+	config = envSchema.parse(process.env);
+} catch (err) {
+	logger.error({ err }, "FATAL: Invalid environment configuration");
+	process.exit(1);
+}
+
+if (config.NODE_ENV !== "production") {
+	if (!process.env.CSRF_SECRET) {
+		logger.warn(
+			"[config] CSRF_SECRET is not set — using insecure dev fallback. " +
+				"Set CSRF_SECRET in .env for any non-development environment.",
+		);
+	}
+	if (!process.env.WEBHOOK_SECRET) {
+		logger.warn(
+			"[config] WEBHOOK_SECRET is not set — using insecure dev fallback. " +
+				"Set WEBHOOK_SECRET in .env for any non-development environment.",
+		);
+	}
+}
+
+export { config };

package/backend/src/lib/db.ts

@@ -0,0 +1,7 @@
+import * as schema from "@hiai-docs/db/schema";
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import { config } from "./config";
+
+const client = postgres(config.DATABASE_URL);
+export const db = drizzle(client, { schema });

package/backend/src/lib/embedding-queue.ts

@@ -0,0 +1,12 @@
+import { logger } from "./logger";
+import { redis } from "./redis";
+
+const QUEUE_KEY = "hiai-docs:embedding-queue";
+
+export function enqueueEmbedding(documentId: string): void {
+	redis.lpush(QUEUE_KEY, documentId).catch((err) => {
+		logger.error({ err, documentId }, "Failed to enqueue embedding job");
+	});
+}
+
+export { startEmbeddingWorker } from "../embedding/worker";

package/backend/src/lib/logger.ts

@@ -0,0 +1,18 @@
+import pino from "pino";
+
+// Read env directly to avoid circular dependency with config.ts
+const level = (process.env.LOG_LEVEL ?? "info") as
+	| "trace"
+	| "debug"
+	| "info"
+	| "warn"
+	| "error"
+	| "fatal";
+const isDev = process.env.NODE_ENV === "development";
+
+export const logger = pino({
+	level,
+	transport: isDev
+		? { target: "pino-pretty", options: { colorize: true } }
+		: undefined,
+});

package/backend/src/lib/markdown-to-doc.ts

@@ -0,0 +1,45 @@
+import Highlight from "@tiptap/extension-highlight";
+import Image from "@tiptap/extension-image";
+import Link from "@tiptap/extension-link";
+import { generateJSON } from "@tiptap/html/server";
+import StarterKit from "@tiptap/starter-kit";
+import { marked } from "marked";
+import { logger } from "./logger";
+
+/**
+ * TipTap extension set used by the editor on the frontend
+ * (see frontend/src/lib/components/editor/HiAiEditor.svelte).
+ * Mirrored here so imported `.md`/`.txt`/`.markdown` files produce
+ * ProseMirror JSON the editor renders with full formatting.
+ *
+ * Excludes extensions that have no markdown equivalent or that need
+ * runtime resources the backend does not load (Collaboration, CodeBlockLowlight).
+ */
+const editorExtensions = [
+	StarterKit.configure({
+		heading: { levels: [1, 2, 3] },
+		codeBlock: false,
+		link: false,
+	}),
+	Link.configure({ openOnClick: false }),
+	Image.configure({ inline: false, allowBase64: false }),
+	Highlight.configure({ multicolor: true }),
+];
+
+/**
+ * Convert raw markdown text to TipTap/ProseMirror JSON that the editor
+ * accepts as `contentJson`. Returns `null` for empty input or on failure
+ * so the import handler can fall back to storing the raw text only.
+ */
+export async function markdownToDocJson(
+	markdown: string,
+): Promise<unknown | null> {
+	if (!markdown.trim()) return null;
+	try {
+		const html = await marked.parse(markdown, { async: true });
+		return generateJSON(html, editorExtensions);
+	} catch (err) {
+		logger.error({ err }, "markdownToDocJson failed");
+		return null;
+	}
+}

package/backend/src/lib/minio.ts

@@ -0,0 +1,46 @@
+import { Client } from "minio";
+import { config } from "./config";
+import { logger } from "./logger";
+
+export const minio = new Client({
+	endPoint: config.MINIO_ENDPOINT,
+	port: config.MINIO_PORT,
+	useSSL: false,
+	accessKey: config.MINIO_ACCESS_KEY,
+	secretKey: config.MINIO_SECRET_KEY,
+	region: "us-east-1",
+});
+
+/**
+ * Public-facing MinIO client used to sign presigned URLs.
+ *
+ * MinIO validates the URL signature against the Host header at request time,
+ * so a URL signed for the Docker-internal `minio:9000` endpoint is rejected
+ * (403) when the browser fetches it via `localhost:9020`. This client signs
+ * against the browser-resolvable host/port instead.
+ *
+ * Note: `region` is required explicitly. Without it, minio-js issues a HEAD
+ * request for region auto-detection, which fail with ECONNREFUSED inside the
+ * container because the public host/port (localhost:9020) is unreachable.
+ */
+export const minioPublic = new Client({
+	endPoint: config.MINIO_PUBLIC_ENDPOINT,
+	port: config.MINIO_PUBLIC_PORT,
+	useSSL: false,
+	accessKey: config.MINIO_ACCESS_KEY,
+	secretKey: config.MINIO_SECRET_KEY,
+	region: "us-east-1",
+});
+
+export const BUCKET = config.MINIO_BUCKET;
+
+export async function ensureBucket(
+	client: Client,
+	bucket: string,
+): Promise<void> {
+	const exists = await client.bucketExists(bucket);
+	if (!exists) {
+		await client.makeBucket(bucket, "us-east-1");
+		logger.info({ bucket }, "Created MinIO bucket");
+	}
+}

package/backend/src/lib/redis.ts

@@ -0,0 +1,19 @@
+import Redis from "ioredis";
+import { config } from "./config";
+import { logger } from "./logger";
+
+export const redis = new Redis(config.REDIS_URL, {
+	maxRetriesPerRequest: 3,
+	retryStrategy(times) {
+		const delay = Math.min(times * 200, 2000);
+		return delay;
+	},
+});
+
+redis.on("error", (err) => {
+	logger.error({ err }, "Redis connection error");
+});
+
+redis.on("connect", () => {
+	logger.info("Redis connected");
+});