Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

feat: add GitHub webhook handling and workspace access validation

Andrej Acevski49f416fd6466
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.json
index d92228a1a..10a297f72 100644
--- a/biome.json
+++ b/biome.json
@@ -19,7 +19,8 @@
"!**/.source",
"!**/.next",
"!**/out",
- "!**/.cache"
+ "!**/.cache",
+ "!**/.claude"
]
},
"formatter": {