@hiai-gg/docsmint 0.4.7 → 0.4.9

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.9",
       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/dist/backend-api-key-facade.js

@@ -0,0 +1,749 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// ../db/src/schema.ts
+var exports_schema = {};
+__export(exports_schema, {
+  versions: () => versions,
+  versionRelations: () => versionRelations,
+  verifications: () => verifications,
+  users: () => users,
+  tags: () => tags,
+  tagRelations: () => tagRelations,
+  shareRoleEnum: () => shareRoleEnum,
+  shareLinks: () => shareLinks,
+  shareLinkRelations: () => shareLinkRelations,
+  sessions: () => sessions,
+  pipelineStatusEnum: () => pipelineStatusEnum,
+  pipelineStageEnum: () => pipelineStageEnum,
+  lifecycleOperations: () => lifecycleOperations,
+  lifecycleOperationStatusEnum: () => lifecycleOperationStatusEnum,
+  lifecycleOperationKindEnum: () => lifecycleOperationKindEnum,
+  guestAccessRelations: () => guestAccessRelations,
+  guestAccess: () => guestAccess,
+  folders: () => folders,
+  folderRelations: () => folderRelations,
+  embeddingStatusEnum: () => embeddingStatusEnum,
+  documents: () => documents,
+  documentVisibilityEnum: () => documentVisibilityEnum,
+  documentTags: () => documentTags,
+  documentTagRelations: () => documentTagRelations,
+  documentRelations: () => documentRelations,
+  documentPipelineRuns: () => documentPipelineRuns,
+  documentPipelineBatches: () => documentPipelineBatches,
+  documentEmbeddings: () => documentEmbeddings,
+  documentEmbeddingRelations: () => documentEmbeddingRelations,
+  documentCreateOperations: () => documentCreateOperations,
+  categoryRelations: () => categoryRelations,
+  categories: () => categories,
+  auditLog: () => auditLog,
+  attachments: () => attachments,
+  attachmentRelations: () => attachmentRelations,
+  apiKeys: () => apiKeys,
+  apiKeyRelations: () => apiKeyRelations,
+  accounts: () => accounts
+});
+import { pgTable, uuid, text, timestamp, bigint, jsonb, index, uniqueIndex, customType, boolean, check, integer, pgEnum } from "drizzle-orm/pg-core";
+import { relations, sql } from "drizzle-orm";
+var vector = customType({
+  dataType(config) {
+    return `vector(${config.dimensions})`;
+  },
+  toDriver(value) {
+    return JSON.stringify(value);
+  },
+  fromDriver(value) {
+    if (typeof value === "string")
+      return JSON.parse(value);
+    return value;
+  }
+});
+var tsvector = customType({
+  dataType() {
+    return "tsvector";
+  }
+});
+var documentVisibilityEnum = pgEnum("document_visibility", ["private", "shared", "public"]);
+var shareRoleEnum = pgEnum("share_role", ["viewer", "commenter", "editor"]);
+var embeddingStatusEnum = pgEnum("embedding_status", [
+  "pending",
+  "processing",
+  "ready",
+  "failed",
+  "stale"
+]);
+var pipelineStageEnum = pgEnum("pipeline_stage", [
+  "prepare",
+  "embed",
+  "graph",
+  "summarize",
+  "finalize"
+]);
+var pipelineStatusEnum = pgEnum("pipeline_status", [
+  "pending",
+  "processing",
+  "ready",
+  "retrying",
+  "failed",
+  "ready_with_warnings",
+  "skipped",
+  "cancelled"
+]);
+var lifecycleOperationKindEnum = pgEnum("lifecycle_operation_kind", [
+  "export",
+  "purge"
+]);
+var lifecycleOperationStatusEnum = pgEnum("lifecycle_operation_status", [
+  "pending",
+  "running",
+  "retryable",
+  "completed",
+  "rejected"
+]);
+var users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  email: text("email").notNull().unique(),
+  name: text("name"),
+  emailVerified: boolean("email_verified").default(false),
+  image: text("image"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+});
+var sessions = pgTable("sessions", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  token: text("token").notNull().unique(),
+  expiresAt: timestamp("expires_at").notNull(),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  revokedAt: timestamp("revoked_at"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  index("sessions_user_id_idx").on(table.userId),
+  index("sessions_revoked_at_idx").on(table.revokedAt).where(sql`${table.revokedAt} IS NOT NULL`)
+]);
+var accounts = pgTable("accounts", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  accountId: text("account_id").notNull(),
+  providerId: text("provider_id").notNull(),
+  accessToken: text("access_token"),
+  refreshToken: text("refresh_token"),
+  accessTokenExpiresAt: timestamp("access_token_expires_at"),
+  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+  scope: text("scope"),
+  password: text("password"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  index("accounts_user_id_idx").on(table.userId),
+  uniqueIndex("accounts_provider_account_idx").on(table.providerId, table.accountId)
+]);
+var verifications = pgTable("verifications", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  index("verifications_identifier_idx").on(table.identifier)
+]);
+var folders = pgTable("folders", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  ownerId: uuid("owner_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  parentId: uuid("parent_id").references(() => folders.id, {
+    onDelete: "set null"
+  }),
+  categoryId: uuid("category_id").references(() => categories.id, {
+    onDelete: "set null"
+  }),
+  name: text("name").notNull(),
+  order: integer("order").notNull().default(0),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  index("folders_owner_id_idx").on(table.ownerId),
+  index("folders_parent_id_idx").on(table.parentId),
+  index("folders_category_id_idx").on(table.categoryId)
+]);
+var folderRelations = relations(folders, ({ one, many }) => ({
+  owner: one(users, { fields: [folders.ownerId], references: [users.id] }),
+  parent: one(folders, {
+    fields: [folders.parentId],
+    references: [folders.id],
+    relationName: "folderParent"
+  }),
+  category: one(categories, {
+    fields: [folders.categoryId],
+    references: [categories.id]
+  }),
+  children: many(folders, { relationName: "folderParent" }),
+  documents: many(documents)
+}));
+var documents = pgTable("documents", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  ownerId: uuid("owner_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  folderId: uuid("folder_id").references(() => folders.id, {
+    onDelete: "set null"
+  }),
+  categoryId: uuid("category_id").references(() => categories.id, {
+    onDelete: "set null"
+  }),
+  title: text("title").notNull().default("Untitled"),
+  content: text("content").default(""),
+  contentJson: jsonb("content_json"),
+  metadata: jsonb("metadata"),
+  visibility: documentVisibilityEnum("visibility").notNull().default("private"),
+  contentHash: text("content_hash"),
+  lastSignificantHash: text("last_significant_hash"),
+  lastSignificantUpdateAt: timestamp("last_significant_update_at"),
+  pendingMinorChanges: boolean("pending_minor_changes").default(false).notNull(),
+  metadataChangedAt: timestamp("metadata_changed_at"),
+  searchVector: tsvector("search_vector").generatedAlwaysAs(sql`to_tsvector('english', left(COALESCE(title, '') || ' ' || regexp_replace(COALESCE(content, ''), 'data:[^[:space:])>]+', ' ', 'g'), 200000))`),
+  searchVectorSimple: tsvector("search_vector_simple").generatedAlwaysAs(sql`to_tsvector('simple', left(COALESCE(title, '') || ' ' || regexp_replace(COALESCE(content, ''), 'data:[^[:space:])>]+', ' ', 'g'), 200000))`),
+  embeddingStatus: embeddingStatusEnum("embedding_status").notNull().default("pending"),
+  activeEmbeddingGeneration: uuid("active_embedding_generation"),
+  pendingEmbeddingGeneration: uuid("pending_embedding_generation"),
+  embeddingProfile: text("embedding_profile"),
+  embeddingErrorCode: text("embedding_error_code"),
+  embeddingUpdatedAt: timestamp("embedding_updated_at"),
+  deletedAt: timestamp("deleted_at"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  index("documents_owner_id_idx").on(table.ownerId),
+  index("documents_folder_id_idx").on(table.folderId),
+  index("documents_category_id_idx").on(table.categoryId),
+  index("documents_created_at_idx").on(table.createdAt),
+  index("idx_documents_search_vector").using("gin", table.searchVector),
+  index("idx_documents_search_vector_simple").using("gin", table.searchVectorSimple),
+  index("documents_embedding_status_idx").on(table.embeddingStatus),
+  index("documents_workspace_deleted_at_idx").on(table.workspaceId, table.deletedAt),
+  index("idx_documents_title_trgm").using("gin", sql`${table.title} gin_trgm_ops`)
+]);
+var documentRelations = relations(documents, ({ one, many }) => ({
+  owner: one(users, { fields: [documents.ownerId], references: [users.id] }),
+  folder: one(folders, {
+    fields: [documents.folderId],
+    references: [folders.id]
+  }),
+  category: one(categories, {
+    fields: [documents.categoryId],
+    references: [categories.id]
+  }),
+  tags: many(documentTags),
+  attachments: many(attachments),
+  versions: many(versions)
+}));
+var documentPipelineRuns = pgTable("document_pipeline_runs", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+  ownerId: uuid("owner_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  generationId: uuid("generation_id").notNull(),
+  revision: text("revision").notNull(),
+  source: text("source").notNull(),
+  status: pipelineStatusEnum("status").notNull().default("pending"),
+  prepareStatus: pipelineStatusEnum("prepare_status").notNull().default("pending"),
+  embedStatus: pipelineStatusEnum("embed_status").notNull().default("pending"),
+  graphStatus: pipelineStatusEnum("graph_status").notNull().default("pending"),
+  summarizeStatus: pipelineStatusEnum("summarize_status").notNull().default("pending"),
+  finalizeStatus: pipelineStatusEnum("finalize_status").notNull().default("pending"),
+  totalBatches: integer("total_batches").notNull().default(0),
+  completedBatches: integer("completed_batches").notNull().default(0),
+  failedBatches: integer("failed_batches").notNull().default(0),
+  errorCode: text("error_code"),
+  attempts: integer("attempts").notNull().default(0),
+  requestedAt: timestamp("requested_at").defaultNow().notNull(),
+  startedAt: timestamp("started_at"),
+  completedAt: timestamp("completed_at"),
+  heartbeatAt: timestamp("heartbeat_at"),
+  availableAt: timestamp("available_at"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  uniqueIndex("document_pipeline_runs_document_generation_idx").on(table.documentId, table.generationId),
+  index("document_pipeline_runs_owner_status_updated_idx").on(table.ownerId, table.status, table.updatedAt)
+]);
+var documentPipelineBatches = pgTable("document_pipeline_batches", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  workspaceId: text("workspace_id"),
+  documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+  generationId: uuid("generation_id").notNull(),
+  batchIndex: integer("batch_index").notNull(),
+  stage: pipelineStageEnum("stage").notNull().default("embed"),
+  chunkStart: integer("chunk_start").notNull(),
+  chunkEnd: integer("chunk_end").notNull(),
+  status: pipelineStatusEnum("status").notNull().default("pending"),
+  attempts: integer("attempts").notNull().default(0),
+  embeddingProfile: text("embedding_profile"),
+  errorCode: text("error_code"),
+  availableAt: timestamp("available_at"),
+  startedAt: timestamp("started_at"),
+  completedAt: timestamp("completed_at"),
+  heartbeatAt: timestamp("heartbeat_at"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  uniqueIndex("document_pipeline_batches_generation_index_idx").on(table.generationId, table.batchIndex),
+  index("document_pipeline_batches_stage_status_available_idx").on(table.stage, table.status, table.availableAt),
+  index("document_pipeline_batches_document_id_idx").on(table.documentId)
+]);
+var tags = pgTable("tags", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  ownerId: uuid("owner_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  name: text("name").notNull(),
+  color: text("color"),
+  createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => [
+  index("tags_owner_id_idx").on(table.ownerId),
+  uniqueIndex("tags_owner_name_idx").on(table.ownerId, table.name)
+]);
+var tagRelations = relations(tags, ({ many }) => ({
+  documents: many(documentTags)
+}));
+var categories = pgTable("categories", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  ownerId: uuid("owner_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  name: text("name").notNull(),
+  order: integer("order").notNull().default(0),
+  apiMode: text("api_mode").notNull().default("unavailable"),
+  apiPermissionRead: boolean("api_permission_read").notNull().default(false),
+  apiPermissionEdit: boolean("api_permission_edit").notNull().default(false),
+  apiPermissionWrite: boolean("api_permission_write").notNull().default(false),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => [
+  index("categories_owner_id_idx").on(table.ownerId),
+  index("categories_api_mode_idx").on(table.apiMode)
+]);
+var categoryRelations = relations(categories, ({ one, many }) => ({
+  owner: one(users, { fields: [categories.ownerId], references: [users.id] }),
+  folders: many(folders),
+  documents: many(documents)
+}));
+var documentTags = pgTable("document_tags", {
+  workspaceId: text("workspace_id"),
+  documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+  tagId: uuid("tag_id").notNull().references(() => tags.id, { onDelete: "cascade" })
+}, (table) => [
+  uniqueIndex("document_tags_unique_idx").on(table.documentId, table.tagId)
+]);
+var documentTagRelations = relations(documentTags, ({ one }) => ({
+  document: one(documents, {
+    fields: [documentTags.documentId],
+    references: [documents.id]
+  }),
+  tag: one(tags, { fields: [documentTags.tagId], references: [tags.id] })
+}));
+var shareLinks = pgTable("share_links", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  documentId: uuid("document_id").references(() => documents.id, {
+    onDelete: "cascade"
+  }),
+  folderId: uuid("folder_id").references(() => folders.id, {
+    onDelete: "cascade"
+  }),
+  categoryId: uuid("category_id").references(() => categories.id, {
+    onDelete: "cascade"
+  }),
+  token: text("token").notNull().unique(),
+  passwordHash: text("password_hash"),
+  role: shareRoleEnum("role").notNull().default("viewer"),
+  expiresAt: timestamp("expires_at"),
+  createdBy: uuid("created_by").notNull().references(() => users.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => [
+  index("share_links_token_idx").on(table.token),
+  index("share_links_document_id_idx").on(table.documentId),
+  index("share_links_folder_id_idx").on(table.folderId),
+  index("share_links_category_id_idx").on(table.categoryId),
+  check("share_links_exactly_one_target_check", sql`num_nonnulls(${table.documentId}, ${table.folderId}, ${table.categoryId}) = 1`)
+]);
+var shareLinkRelations = relations(shareLinks, ({ one, many }) => ({
+  document: one(documents, {
+    fields: [shareLinks.documentId],
+    references: [documents.id]
+  }),
+  folder: one(folders, {
+    fields: [shareLinks.folderId],
+    references: [folders.id]
+  }),
+  category: one(categories, {
+    fields: [shareLinks.categoryId],
+    references: [categories.id]
+  }),
+  creator: one(users, {
+    fields: [shareLinks.createdBy],
+    references: [users.id]
+  }),
+  guestAccess: many(guestAccess)
+}));
+var guestAccess = pgTable("guest_access", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  shareLinkId: uuid("share_link_id").notNull().references(() => shareLinks.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  guestEmail: text("guest_email").notNull(),
+  grantedAt: timestamp("granted_at").defaultNow().notNull()
+}, (table) => [index("guest_access_share_link_idx").on(table.shareLinkId)]);
+var guestAccessRelations = relations(guestAccess, ({ one }) => ({
+  shareLink: one(shareLinks, {
+    fields: [guestAccess.shareLinkId],
+    references: [shareLinks.id]
+  })
+}));
+var attachments = pgTable("attachments", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  filename: text("filename").notNull(),
+  mimeType: text("mime_type").notNull(),
+  size: bigint("size", { mode: "number" }).notNull(),
+  storageKey: text("storage_key").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => [index("attachments_document_id_idx").on(table.documentId)]);
+var attachmentRelations = relations(attachments, ({ one }) => ({
+  document: one(documents, {
+    fields: [attachments.documentId],
+    references: [documents.id]
+  })
+}));
+var versions = pgTable("versions", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  content: text("content").notNull(),
+  contentJson: jsonb("content_json"),
+  createdBy: uuid("created_by").notNull().references(() => users.id, { onDelete: "cascade" }),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  label: text("label"),
+  description: text("description"),
+  isSnapshot: boolean("is_snapshot").default(false),
+  restoredFrom: uuid("restored_from")
+}, (table) => [
+  index("versions_document_id_idx").on(table.documentId),
+  index("versions_created_at_idx").on(table.createdAt),
+  index("versions_is_snapshot_idx").on(table.isSnapshot)
+]);
+var documentEmbeddings = pgTable("document_embeddings", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  chunkIndex: bigint("chunk_index", { mode: "number" }).notNull(),
+  chunkText: text("chunk_text").notNull(),
+  chunkHash: text("chunk_hash"),
+  charStart: integer("char_start").notNull().default(0),
+  charEnd: integer("char_end").notNull().default(0),
+  embedding: vector("embedding", { dimensions: 1024 }),
+  embeddingModel: text("embedding_model").notNull().default(""),
+  generationId: uuid("generation_id").notNull(),
+  embeddingDimensions: integer("embedding_dimensions").notNull().default(1024),
+  embeddingProfile: text("embedding_profile").notNull().default("legacy"),
+  isValid: boolean("is_valid").notNull().default(false),
+  createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => [
+  index("document_embeddings_doc_id_idx").on(table.documentId),
+  uniqueIndex("document_embeddings_doc_chunk_idx").on(table.documentId, table.generationId, table.chunkIndex),
+  index("document_embeddings_generation_valid_idx").on(table.documentId, table.generationId, table.isValid),
+  index("idx_document_embeddings_embedding_model").on(table.embeddingModel),
+  index("idx_document_embeddings_hnsw").using("hnsw", sql`${table.embedding} vector_cosine_ops`),
+  index("idx_document_embeddings_diskann").using("diskann", sql`${table.embedding} vector_cosine_ops`)
+]);
+var documentEmbeddingRelations = relations(documentEmbeddings, ({ one }) => ({
+  document: one(documents, {
+    fields: [documentEmbeddings.documentId],
+    references: [documents.id]
+  })
+}));
+var apiKeys = pgTable("api_keys", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  ownerId: uuid("owner_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  workspaceId: text("workspace_id"),
+  name: text("name").notNull(),
+  keyHash: text("key_hash").notNull().unique(),
+  prefix: text("prefix").notNull(),
+  encryptedKey: text("encrypted_key"),
+  scopes: jsonb("scopes").notNull().default("[]"),
+  lastUsedAt: timestamp("last_used_at"),
+  expiresAt: timestamp("expires_at"),
+  createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => [
+  index("idx_api_keys_owner").on(table.ownerId),
+  index("idx_api_keys_prefix").on(table.prefix)
+]);
+var apiKeyRelations = relations(apiKeys, ({ one }) => ({
+  owner: one(users, { fields: [apiKeys.ownerId], references: [users.id] })
+}));
+var auditLog = pgTable("audit_log", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  actorId: uuid("actor_id").notNull(),
+  workspaceId: text("workspace_id"),
+  action: text("action").notNull(),
+  resourceType: text("resource_type").notNull(),
+  resourceId: uuid("resource_id"),
+  details: jsonb("details").notNull().default("{}"),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => [
+  index("idx_audit_log_actor").on(table.actorId),
+  index("idx_audit_log_resource").on(table.resourceType, table.resourceId),
+  index("idx_audit_log_created").on(table.createdAt)
+]);
+var lifecycleOperations = pgTable("lifecycle_operations", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  actorUserId: uuid("actor_user_id").references(() => users.id, { onDelete: "set null" }),
+  actorSubjectHash: text("actor_subject_hash").notNull(),
+  idempotencyKey: text("idempotency_key").notNull(),
+  operationKind: lifecycleOperationKindEnum("operation_kind").notNull(),
+  status: lifecycleOperationStatusEnum("status").notNull().default("pending"),
+  leaseOwner: text("lease_owner"),
+  leaseExpiresAt: timestamp("lease_expires_at"),
+  fenceTokenHash: text("fence_token_hash"),
+  completedSteps: jsonb("completed_steps").notNull().default("[]"),
+  terminalResult: jsonb("terminal_result"),
+  safeErrorCode: text("safe_error_code"),
+  attemptCount: integer("attempt_count").notNull().default(0),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  completedAt: timestamp("completed_at")
+}, (table) => [
+  uniqueIndex("lifecycle_operations_actor_idempotency_idx").on(table.actorUserId, table.idempotencyKey),
+  index("lifecycle_operations_status_lease_idx").on(table.status, table.leaseExpiresAt),
+  index("lifecycle_operations_actor_idx").on(table.actorUserId),
+  index("lifecycle_operations_retryable_idx").on(table.status).where(sql`${table.status} = 'retryable'`),
+  check("lifecycle_operations_actor_subject_hash", sql`${table.actorSubjectHash} ~ '^[a-f0-9]{64}$'`)
+]);
+var documentCreateOperations = pgTable("document_create_operations", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  workspaceId: text("workspace_id").notNull(),
+  actorUserId: uuid("actor_user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  idempotencyKey: text("idempotency_key").notNull(),
+  documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+  createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => [
+  uniqueIndex("document_create_operations_workspace_actor_key_idx").on(table.workspaceId, table.actorUserId, table.idempotencyKey),
+  uniqueIndex("document_create_operations_document_idx").on(table.documentId)
+]);
+var versionRelations = relations(versions, ({ one }) => ({
+  document: one(documents, {
+    fields: [versions.documentId],
+    references: [documents.id]
+  }),
+  creator: one(users, {
+    fields: [versions.createdBy],
+    references: [users.id]
+  })
+}));
+
+// ../db/src/with-tenant.ts
+import { sql as sql2 } from "drizzle-orm";
+
+// ../db/src/client.ts
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+var databaseUrl = process.env.DATABASE_URL || "postgresql://hiai_app:changeme@localhost:5437/hiai_docs";
+var client = postgres(databaseUrl, {
+  max: 20,
+  idle_timeout: 30,
+  connect_timeout: 10
+});
+var db = drizzle(client, { schema: exports_schema });
+
+// ../db/src/with-tenant.ts
+var ZERO_UUID = "00000000-0000-0000-0000-000000000000";
+function adminTenantContext(ownerId) {
+  const resolved = ownerId ?? process.env.OWNER_ID;
+  if (!resolved) {
+    console.warn("[hiai-docs/db] adminTenantContext: ownerId not provided and OWNER_ID env not set, using empty string");
+  }
+  return {
+    userId: resolved ?? "",
+    role: "admin"
+  };
+}
+async function withTenant(ctx, fn) {
+  return db.transaction(async (tx) => {
+    await tx.execute(sql2`SELECT set_config('app.current_user_id', ${ctx.userId}, true)`);
+    await tx.execute(sql2`SELECT set_config('app.current_user_role', ${ctx.role}, true)`);
+    await tx.execute(sql2`SELECT set_config('app.current_workspace_id', ${ctx.workspaceId ?? ""}, true)`);
+    return fn(tx);
+  });
+}
+
+// ../../backend/src/lib/api-keys.ts
+import { and, desc, eq } from "drizzle-orm";
+
+// ../../backend/src/lib/api-key-encryption.ts
+var VERSION = "v1";
+var AAD = new TextEncoder().encode("hiai-docs:category-api-key:v1");
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function base64ToBytes(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let index2 = 0;index2 < binary.length; index2 += 1) {
+    bytes[index2] = binary.charCodeAt(index2);
+  }
+  return bytes;
+}
+async function importEncryptionKey(secret) {
+  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"
+  ]);
+}
+async function encryptApiKey(rawKey, secret) {
+  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))}`;
+}
+async function decryptApiKey(payload, secret) {
+  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);
+}
+
+// ../../backend/src/lib/api-keys.ts
+var API_KEY_ADMIN_TENANT = adminTenantContext(ZERO_UUID);
+var GLOBAL_API_SCOPE = "global";
+var 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)$/;
+function parseApiKeyScopes(value) {
+  if (!Array.isArray(value) || value.length === 0)
+    return null;
+  const scopes = [];
+  const seen = new Set;
+  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);
+  }
+  return scopes;
+}
+function buildCategoryApiKeyScopes(categoryId, permissions) {
+  return ["read", "edit", "write"].filter((permission) => permissions[permission]).map((permission) => `category:${categoryId}:${permission}`);
+}
+function categoryIdFromApiKeyScopes(scopes) {
+  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;
+}
+function hashKey(key) {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(key);
+  return hasher.digest("hex");
+}
+async function createApiKey(ownerId, name, scopes, expiresAt, options) {
+  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 };
+}
+async function revealCategoryApiKey(id, ownerId, encryptionSecret) {
+  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 ?? [];
+  if (!categoryIdFromApiKeyScopes(scopes))
+    return null;
+  return decryptApiKey(row.encryptedKey, encryptionSecret);
+}
+async function revokeApiKey(id, ownerId) {
+  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;
+}
+async function validateApiKey(key) {
+  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;
+  }
+  if (row.expiresAt && new Date(row.expiresAt) < new Date) {
+    return null;
+  }
+  const scopes = parseApiKeyScopes(row.scopes ?? []);
+  if (!scopes)
+    return null;
+  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
+  };
+}
+export {
+  validateApiKey as verifyApiKey,
+  revokeApiKey,
+  revealCategoryApiKey,
+  createApiKey as issueApiKey,
+  buildCategoryApiKeyScopes,
+  GLOBAL_API_SCOPE
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiai-gg/docsmint",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "type": "module",
   "browser": {
     "./dist/backend-launcher.js": false,
@@ -89,7 +89,7 @@
       "types": "./dist/storage-quota.d.ts"
     },
     "./backend/lib/api-key-facade": {
-      "import": "./backend/src/lib/api-key-facade.ts",
+      "import": "./dist/backend-api-key-facade.js",
       "types": "./backend/src/lib/api-key-facade.ts"
     },
     "./frontend/app-shell": {
@@ -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.9";
 
 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.9",
 });
 
 /**