⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
feat: add GitHub webhook handling and workspace access validation
Andrej Acevski49f416fd6466
diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 000000000..0e063bdcb--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1,287 @@+# CLAUDE.md++This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.++## Project Overview++Kaneo is a self-hosted project management platform built with simplicity and performance as core principles. The codebase is organized as a **pnpm monorepo** with TurboRepo.++**Key Philosophy**: Features exist to solve real problems, not to impress. Avoid over-engineering - keep solutions simple and focused. Don't add features, refactoring, or improvements beyond what was asked.++## Development Commands++### Getting Started+```bash+# Install dependencies (uses pnpm)+pnpm install++# Start all development servers (API + web)+pnpm dev++# Lint and auto-fix code (Biome)+pnpm lint++# Build all packages+pnpm build+```++### API-Specific Commands+```bash+# Run API in development mode+pnpm --filter @kaneo/api dev++# Build API+pnpm --filter @kaneo/api build++# Generate database migrations (after schema changes)+pnpm --filter @kaneo/api db:generate++# Run database migrations (auto-runs on API startup)+pnpm --filter @kaneo/api db:migrate++# Open Drizzle Studio (database GUI)+pnpm --filter @kaneo/api db:studio++# Lint API code+pnpm --filter @kaneo/api lint+```++### Web-Specific Commands+```bash+# Run web app in development mode+pnpm --filter @kaneo/web dev++# Build web app for production+pnpm --filter @kaneo/web build++# Preview production build+pnpm --filter @kaneo/web preview++# Lint web code+pnpm --filter @kaneo/web lint+```++## Architecture Overview++### Monorepo Structure+```+kaneo/+├── apps/+│ ├── api/ # Backend API (Hono/Node.js/PostgreSQL)+│ ├── web/ # Frontend app (React/Vite/TanStack)+│ └── docs/ # Documentation site (Next.js)+├── packages/+│ ├── email/ # Email utilities+│ ├── libs/ # Shared libraries+│ └── typescript-config/ # TypeScript configurations+└── charts/ # Kubernetes Helm charts+```++### Technology Stack++**Backend (API)**+- Framework: Hono (lightweight web framework)+- Database: PostgreSQL with Drizzle ORM+- Authentication: Better Auth+- Validation: Valibot+- API Documentation: OpenAPI (hono-openapi)+- IDs: CUID2 (via @paralleldrive/cuid2)++**Frontend (Web)**+- Framework: React 19++- Routing: TanStack Router (file-based)+- Data Fetching: TanStack Query (React Query)+- Build Tool: Vite+- Styling: Tailwind CSS v4+- State Management: Zustand+- UI Components: Radix UI primitives++### Key Architectural Patterns++**Backend API Structure**+- Routes organized by feature in `apps/api/src/{feature}/`+- Controller pattern: business logic extracted to `{feature}/controllers/`+- All routes use OpenAPI decorators (`describeRoute`)+- All inputs validated with Valibot schemas+- Migrations auto-run on API startup++**Frontend Structure**+- File-based routing in `apps/web/src/routes/`+- Query hooks in `apps/web/src/hooks/queries/`+- Mutation hooks in `apps/web/src/hooks/mutations/`+- API fetchers in `apps/web/src/fetchers/{feature}/`+- Components in `apps/web/src/components/`++**Database Schema Conventions**+- All tables use CUID2 for primary keys (`createId()`)+- Every table has `createdAt` and `updatedAt` timestamps+- Foreign keys always specify cascade behavior (`onDelete`, `onUpdate`)+- Indexes on frequently queried columns (especially foreign keys)+- Schema defined in `apps/api/src/database/schema.ts`+- Relations defined in `apps/api/src/database/relations.ts`++**Authentication Flow**+- Better Auth handles authentication+- User context available in Hono via `c.get("userId")`, `c.get("user")`, `c.get("session")`+- API keys supported via Bearer token+- Frontend uses Better Auth client from `@/lib/auth-client`++**Event System**+- Events published for activity tracking+- Use `publishEvent()` from `apps/api/src/events/`+- Events tracked for features like status changes, assignments, etc.++## Code Style++### Formatting (Biome)+- **Indentation**: Tabs for TypeScript/TSX+- **Quotes**: Double quotes+- **Semicolons**: Required+- Run `pnpm lint` to auto-fix++### TypeScript Conventions+- Prefer `type` over `interface` (only use interface when extending/merging)+- Prefer type inference when obvious+- File naming: PascalCase for components, kebab-case for utilities/hooks+- Hooks use `use` prefix: `use-task.ts`++### Import Organization+1. External packages+2. Internal packages (`@/` aliases)+3. Relative imports+Biome auto-organizes imports.++### Git Commits+Use Conventional Commits:+- `feat:` - New features+- `fix:` - Bug fixes+- `docs:` - Documentation+- `refactor:` - Code refactoring+- `chore:` - Maintenance tasks++Husky enforces commit message format via commitlint.++## Environment Configuration++**Single `.env` file** in project root shared by all apps.++Required variables:+- `KANEO_CLIENT_URL` - Web app URL (e.g., http://localhost:5173)+- `KANEO_API_URL` - API URL (e.g., http://localhost:1337)+- `AUTH_SECRET` - JWT secret (min 32 chars)+- `DATABASE_URL` - PostgreSQL connection string+- `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`++Optional:+- `CORS_ORIGINS` - Comma-separated allowed origins (empty = allow all in dev)+- `VITE_API_URL` - API URL for web dev (defaults to http://localhost:1337)+- SSO providers (GitHub, Google, Discord, Custom OAuth/OIDC)+- SMTP configuration++See `ENVIRONMENT_SETUP.md` for detailed configuration and troubleshooting.++## Development Workflow++### When Making Changes++1. **Read before modifying**: Never propose changes to code you haven't read+2. **Use existing patterns**: Follow the established controller/fetcher/hook patterns+3. **Avoid over-engineering**: Don't add features beyond what's requested+4. **Type safety**: Let TypeScript guide you - all APIs are fully typed+5. **Validate inputs**: Always use Valibot schemas for API inputs+6. **Error handling**: Backend uses HTTPException, frontend uses toast notifications++### Database Changes++1. Modify schema in `apps/api/src/database/schema.ts`+2. Generate migration: `pnpm --filter @kaneo/api db:generate`+3. Migration auto-runs on next API startup+4. Always use CUID2 for IDs, include timestamps, specify cascade behavior++### Adding API Endpoints++1. Create controller in `apps/api/src/{feature}/controllers/`+2. Add route in `apps/api/src/{feature}/index.ts`+3. Use `describeRoute` for OpenAPI docs+4. Use `validator` with Valibot schema+5. Keep route handler thin - business logic in controller++### Adding Frontend Features++1. Create fetcher in `apps/web/src/fetchers/{feature}/`+2. Create query/mutation hook in `apps/web/src/hooks/`+3. Use TanStack Query for caching+4. Handle loading/error states properly+5. Use toast notifications (sonner) for user feedback++## Important Notes++- **Package Manager**: This project uses **pnpm**, not npm or yarn+- **Migrations**: Auto-run on API startup, stored in `apps/api/drizzle/`+- **Development Ports**: API runs on 1337, web runs on 5173+- **Hot Reload**: Both API and web have watch mode via `pnpm dev`+- **CORS**: Configured in API index.ts, controlled by `CORS_ORIGINS` env var+- **No Tests Yet**: Test infrastructure not currently set up in this codebase+- **Security**: Never commit secrets, always validate inputs, sanitize outputs++## Common Patterns++### Backend Route Example+```typescript+// apps/api/src/{feature}/index.ts+import { Hono } from "hono";+import { describeRoute, validator } from "hono-openapi";+import * as v from "valibot";+import getItem from "./controllers/get-item";++const feature = new Hono<{ Variables: { userId: string } }>()+ .get("/:id",+ describeRoute({+ operationId: "getItem",+ tags: ["Feature"],+ description: "Get item by ID"+ }),+ validator("param", v.object({ id: v.string() })),+ async (c) => {+ const { id } = c.req.valid("param");+ const item = await getItem(id);+ return c.json(item);+ }+ );+```++### Frontend Query Hook Example+```typescript+// apps/web/src/hooks/queries/{feature}/use-item.ts+import { useQuery } from "@tanstack/react-query";+import { getItem } from "@/fetchers/{feature}/get-item";++export function useItem(itemId: string) {+ return useQuery({+ queryKey: ["item", itemId],+ queryFn: () => getItem(itemId),+ });+}+```++### Database Schema Example+```typescript+// apps/api/src/database/schema.ts+export const exampleTable = pgTable("example", {+ id: text("id").$defaultFn(() => createId()).primaryKey(),+ projectId: text("project_id")+ .notNull()+ .references(() => projectTable.id, {+ onDelete: "cascade",+ onUpdate: "cascade",+ }),+ title: text("title").notNull(),+ createdAt: timestamp("created_at", { mode: "date" }).defaultNow().notNull(),+ updatedAt: timestamp("updated_at", { mode: "date" })+ .defaultNow()+ .$onUpdate(() => new Date())+ .notNull(),+}, (table) => [+ index("example_projectId_idx").on(table.projectId),+]);+```diff --git a/apps/api/src/github-integration/index.ts b/apps/api/src/github-integration/index.tsindex b4c2acd4c..5dbc49c99 100644--- a/apps/api/src/github-integration/index.ts+++ b/apps/api/src/github-integration/index.ts@@ -1,11 +1,15 @@import { eq } from "drizzle-orm";+import type { Context } from "hono";import { Hono } from "hono";+import { HTTPException } from "hono/http-exception";import { describeRoute, resolver, validator } from "hono-openapi";import * as v from "valibot";import db from "../database";-import { githubIntegrationTable } from "../database/schema";+import { githubIntegrationTable, projectTable } from "../database/schema";import { subscribeToEvent } from "../events";import { githubIntegrationSchema } from "../schemas";+import { validateWorkspaceAccess } from "../utils/validate-workspace-access";+import { workspaceAccess } from "../utils/workspace-access-middleware";import createGithubIntegration from "./controllers/create-github-integration";import deleteGithubIntegration from "./controllers/delete-github-integration";import getGithubIntegration from "./controllers/get-github-integration";@@ -79,7 +83,17 @@ subscribeToEvent<{title: string;}>("task.priority_changed", handleTaskPriorityChanged);-const githubIntegration = new Hono()+const githubIntegration = new Hono<{+ Variables: {+ userId: string;+ workspaceId: string;+ apiKey?: {+ id: string;+ userId: string;+ enabled: boolean;+ };+ };+}>().get("/app-info",describeRoute({@@ -172,6 +186,7 @@ const githubIntegration = new Hono()},}),validator("param", v.object({ projectId: v.string() })),+ workspaceAccess.fromProject("projectId"),async (c) => {const { projectId } = c.req.valid("param");const integration = await getGithubIntegration(projectId);@@ -201,6 +216,7 @@ const githubIntegration = new Hono()repositoryName: v.pipe(v.string(), v.minLength(1)),}),),+ workspaceAccess.fromProject("projectId"),async (c) => {const { projectId } = c.req.valid("param");const { repositoryOwner, repositoryName } = c.req.valid("json");@@ -244,6 +260,7 @@ const githubIntegration = new Hono()isActive: v.optional(v.boolean()),}),),+ workspaceAccess.fromProject("projectId"),async (c) => {const { projectId } = c.req.valid("param");const { isActive } = c.req.valid("json");@@ -283,6 +300,7 @@ const githubIntegration = new Hono()},}),validator("param", v.object({ projectId: v.string() })),+ workspaceAccess.fromProject("projectId"),async (c) => {const { projectId } = c.req.valid("param");const result = await deleteGithubIntegration(projectId);@@ -310,45 +328,72 @@ const githubIntegration = new Hono()projectId: v.string(),}),),+ async (c, next) => {+ const userId = c.get("userId");+ if (!userId) {+ throw new HTTPException(401, { message: "Unauthorized" });+ }++ const body = await c.req.json();+ const projectId = body.projectId as string;++ const [project] = await db+ .select({ workspaceId: projectTable.workspaceId })+ .from(projectTable)+ .where(eq(projectTable.id, projectId))+ .limit(1);++ if (!project) {+ throw new HTTPException(404, { message: "Project not found" });+ }++ const apiKey = c.get("apiKey");+ const apiKeyId = apiKey?.id;++ await validateWorkspaceAccess(userId, project.workspaceId, apiKeyId);+ c.set("workspaceId", project.workspaceId);++ return next();+ },async (c) => {const { projectId } = c.req.valid("json");const result = await importIssues(projectId);return c.json(result);},- )- .post("/webhook", async (c) => {- try {- if (!githubApp) {- return c.json({ error: "GitHub integration not configured" }, 400);- }+ );- const arrayBuffer = await c.req.arrayBuffer();- const body = Buffer.from(arrayBuffer).toString("utf8");+export async function handleGithubWebhook(c: Context) {+ try {+ if (!githubApp) {+ return c.json({ error: "GitHub integration not configured" }, 400);+ }- const signature = c.req.header("x-hub-signature-256");- if (!signature) {- return c.json({ error: "Missing signature" }, 400);- }+ const arrayBuffer = await c.req.arrayBuffer();+ const body = Buffer.from(arrayBuffer).toString("utf8");- const eventName = c.req.header("x-github-event");- if (!eventName) {- return c.json({ error: "Missing event name" }, 400);- }+ const signature = c.req.header("x-hub-signature-256");+ if (!signature) {+ return c.json({ error: "Missing signature" }, 400);+ }- const deliveryId = c.req.header("x-github-delivery") || "";+ const eventName = c.req.header("x-github-event");+ if (!eventName) {+ return c.json({ error: "Missing event name" }, 400);+ }- await githubApp.webhooks.verifyAndReceive({- id: deliveryId,- name: eventName as "issues" | "pull_request" | "push" | string,- signature,- payload: body,- });+ const deliveryId = c.req.header("x-github-delivery") || "";- return c.json({ status: "success" });- } catch (error) {- console.error("Webhook processing error:", error);- return c.json({ error: "Webhook processing failed" }, 400);- }- });+ await githubApp.webhooks.verifyAndReceive({+ id: deliveryId,+ name: eventName as "issues" | "pull_request" | "push" | string,+ signature,+ payload: body,+ });+ return c.json({ status: "success" });+ } catch (error) {+ console.error("Webhook processing error:", error);+ return c.json({ error: "Webhook processing failed" }, 400);+ }+}export default githubIntegration;diff --git a/apps/api/src/index.ts b/apps/api/src/index.tsindex e9c8ca694..ff6d53309 100644--- a/apps/api/src/index.ts+++ b/apps/api/src/index.ts@@ -9,7 +9,7 @@ import activity from "./activity";import { auth } from "./auth";import config from "./config";import db from "./database";-import githubIntegration from "./github-integration";+import githubIntegration, { handleGithubWebhook } from "./github-integration";import label from "./label";import notification from "./notification";@@ -72,11 +72,6 @@ api.get("/health", (c) => {return c.json({ status: "ok" });});-const githubIntegrationApi = api.route(- "/github-integration",- githubIntegration,-);-api.get("/public-project/:id", async (c) => {const { id } = c.req.param();const project = await getPublicProject(id);@@ -84,6 +79,8 @@ api.get("/public-project/:id", async (c) => {return c.json(project);});+api.post("/github-integration/webhook", handleGithubWebhook);+const configApi = api.route("/config", config);api.get(@@ -170,6 +167,10 @@ const timeEntryApi = api.route("/time-entry", timeEntry);const labelApi = api.route("/label", label);const notificationApi = api.route("/notification", notification);const searchApi = api.route("/search", search);+const githubIntegrationApi = api.route(+ "/github-integration",+ githubIntegration,+);app.route("/api", api);diff --git a/apps/api/src/utils/workspace-access-middleware.ts b/apps/api/src/utils/workspace-access-middleware.tsindex d31820e3a..39b37a7cc 100644--- a/apps/api/src/utils/workspace-access-middleware.ts+++ b/apps/api/src/utils/workspace-access-middleware.ts@@ -24,7 +24,6 @@ export function workspaceAccessMiddleware(return async (c: Context, next: Next) => {const userId = c.get("userId");- console.log({ userId });if (!userId) {throw new HTTPException(401, { message: "Unauthorized" });}@@ -45,7 +44,6 @@ export function workspaceAccessMiddleware(c.req.param(source.idKey) ||c.req.query(source.idKey) ||body[source.idKey];- console.log(source.idKey, source.type, id, source.resource);if (id) {workspaceId = await lookupWorkspaceId(source.resource, id);}@@ -62,7 +60,6 @@ export function workspaceAccessMiddleware(});}- // Get API key ID if present (for API key authentication)const apiKey = c.get("apiKey");const apiKeyId = apiKey?.id;diff --git a/biome.json b/biome.jsonindex d92228a1a..10a297f72 100644--- a/biome.json+++ b/biome.json@@ -19,7 +19,8 @@"!**/.source","!**/.next","!**/out",- "!**/.cache"+ "!**/.cache",+ "!**/.claude"]},"formatter": {