session-collab-mcp 0.3.0

package/bin/session-collab-mcp

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cli = join(__dirname, '..', 'src', 'cli.ts');
+
+spawn('npx', ['tsx', cli], { stdio: 'inherit', shell: true }).on('exit', process.exit);

package/migrations/0001_init.sql

@@ -0,0 +1,72 @@
+-- Session Collaboration MCP - Initial Schema
+-- Database: Cloudflare D1 (SQLite-compatible)
+
+-- Sessions table: track active Claude Code sessions
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    name TEXT,
+    project_root TEXT NOT NULL,
+    machine_id TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    last_heartbeat TEXT DEFAULT (datetime('now')),
+    status TEXT DEFAULT 'active' CHECK (status IN ('active', 'inactive', 'terminated'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_root);
+
+-- Claims table: WIP declarations
+CREATE TABLE IF NOT EXISTS claims (
+    id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    intent TEXT NOT NULL,
+    scope TEXT DEFAULT 'medium' CHECK (scope IN ('small', 'medium', 'large')),
+    status TEXT DEFAULT 'active' CHECK (status IN ('active', 'completed', 'abandoned')),
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now')),
+    completed_summary TEXT,
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_claims_session ON claims(session_id);
+CREATE INDEX IF NOT EXISTS idx_claims_status ON claims(status);
+
+-- Claim files: normalized file paths for efficient querying
+CREATE TABLE IF NOT EXISTS claim_files (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    claim_id TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    is_pattern INTEGER DEFAULT 0,
+    FOREIGN KEY (claim_id) REFERENCES claims(id) ON DELETE CASCADE,
+    UNIQUE(claim_id, file_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_claim_files_path ON claim_files(file_path);
+CREATE INDEX IF NOT EXISTS idx_claim_files_claim ON claim_files(claim_id);
+
+-- Messages table: inter-session communication
+CREATE TABLE IF NOT EXISTS messages (
+    id TEXT PRIMARY KEY,
+    from_session_id TEXT NOT NULL,
+    to_session_id TEXT,
+    content TEXT NOT NULL,
+    read_at TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (from_session_id) REFERENCES sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_to ON messages(to_session_id);
+CREATE INDEX IF NOT EXISTS idx_messages_unread ON messages(to_session_id, read_at);
+
+-- Decisions table: architectural decisions log (optional feature)
+CREATE TABLE IF NOT EXISTS decisions (
+    id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    category TEXT CHECK (category IN ('architecture', 'naming', 'api', 'database', 'ui', 'other')),
+    title TEXT NOT NULL,
+    description TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_category ON decisions(category);

package/migrations/0002_auth.sql

@@ -0,0 +1,56 @@
+-- Authentication & API Token Schema
+-- Migration: 0002_auth.sql
+
+-- Users table: user accounts
+CREATE TABLE IF NOT EXISTS users (
+    id TEXT PRIMARY KEY,
+    email TEXT NOT NULL UNIQUE,
+    password_hash TEXT NOT NULL,
+    display_name TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now')),
+    last_login_at TEXT,
+    status TEXT DEFAULT 'active' CHECK (status IN ('active', 'suspended', 'deleted'))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_users_email ON users(email);
+CREATE INDEX IF NOT EXISTS idx_users_status ON users(status);
+
+-- API Tokens table: user API keys for MCP authentication
+CREATE TABLE IF NOT EXISTS api_tokens (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    token_hash TEXT NOT NULL,
+    token_prefix TEXT NOT NULL,
+    scopes TEXT DEFAULT '["mcp"]',
+    last_used_at TEXT,
+    expires_at TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    revoked_at TEXT,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_tokens_user ON api_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_api_tokens_prefix ON api_tokens(token_prefix);
+CREATE INDEX IF NOT EXISTS idx_api_tokens_hash ON api_tokens(token_hash);
+
+-- Refresh Tokens table: JWT refresh tokens (revocable)
+CREATE TABLE IF NOT EXISTS refresh_tokens (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    token_hash TEXT NOT NULL,
+    expires_at TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    revoked_at TEXT,
+    user_agent TEXT,
+    ip_address TEXT,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user ON refresh_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_refresh_tokens_hash ON refresh_tokens(token_hash);
+
+-- Add user_id column to sessions table for user association
+ALTER TABLE sessions ADD COLUMN user_id TEXT REFERENCES users(id);
+CREATE INDEX IF NOT EXISTS idx_sessions_user ON sessions(user_id);

package/migrations/0002_session_status.sql

@@ -0,0 +1,10 @@
+-- Add work status tracking to sessions
+-- Enables real-time visibility into what each session is working on
+
+-- Add new columns to sessions table
+ALTER TABLE sessions ADD COLUMN current_task TEXT;
+ALTER TABLE sessions ADD COLUMN progress TEXT; -- JSON: {"completed": 3, "total": 5, "percentage": 60}
+ALTER TABLE sessions ADD COLUMN todos TEXT; -- JSON array of todo items
+
+-- Create index for faster queries on active sessions with tasks
+CREATE INDEX IF NOT EXISTS idx_sessions_active_task ON sessions(status, current_task) WHERE status = 'active';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "session-collab-mcp",
+  "version": "0.3.0",
+  "description": "MCP server for Claude Code session collaboration - prevents conflicts between parallel sessions",
+  "type": "module",
+  "bin": {
+    "session-collab-mcp": "./bin/session-collab-mcp"
+  },
+  "files": [
+    "bin",
+    "src",
+    "migrations"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "start": "node dist/cli.js",
+    "start:dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.7.0",
+    "tsx": "^4.19.2",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241218.0",
+    "@types/better-sqlite3": "^7.6.12",
+    "eslint": "^9.17.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "wrangler": "^3.99.0"
+  }
+}

package/src/auth/handlers.ts

@@ -0,0 +1,326 @@
+// Authentication API handlers
+
+import type { D1Database } from '@cloudflare/workers-types';
+import { hashPassword, verifyPassword, validatePasswordStrength } from './password';
+import { createAccessToken, createRefreshToken, verifyJwt, getTokenExpiry } from './jwt';
+import {
+  createUser,
+  getUserByEmail,
+  getUserById,
+  updateUserLastLogin,
+  updateUserPassword,
+  updateUserProfile,
+  toUserPublic,
+  createRefreshToken as createRefreshTokenDb,
+  getRefreshTokenByHash,
+  revokeRefreshToken,
+  revokeAllUserRefreshTokens,
+} from '../db/auth-queries';
+import { sha256 } from '../utils/crypto';
+import {
+  RegisterRequestSchema,
+  LoginRequestSchema,
+  RefreshRequestSchema,
+  UpdateProfileRequestSchema,
+  ChangePasswordRequestSchema,
+  type AuthResponse,
+  type UserResponse,
+  type AuthContext,
+} from './types';
+
+interface HandlerContext {
+  db: D1Database;
+  jwtSecret: string;
+  request: Request;
+}
+
+// CORS headers
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json', ...corsHeaders },
+  });
+}
+
+function errorResponse(error: string, code: string, status: number, details?: { field: string; message: string }[]): Response {
+  return jsonResponse({ error, code, details }, status);
+}
+
+/**
+ * POST /auth/register
+ */
+export async function handleRegister(ctx: HandlerContext): Promise<Response> {
+  const body = await ctx.request.json();
+  const parsed = RegisterRequestSchema.safeParse(body);
+
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((i) => ({
+      field: i.path.join('.'),
+      message: i.message,
+    }));
+    return errorResponse('Validation failed', 'ERR_VALIDATION', 422, details);
+  }
+
+  const { email, password, display_name } = parsed.data;
+
+  // Validate password strength
+  const passwordError = validatePasswordStrength(password);
+  if (passwordError) {
+    return errorResponse(passwordError, 'ERR_WEAK_PASSWORD', 422, [{ field: 'password', message: passwordError }]);
+  }
+
+  // Check if email already exists
+  const existingUser = await getUserByEmail(ctx.db, email);
+  if (existingUser) {
+    return errorResponse('Email already registered', 'ERR_EMAIL_EXISTS', 409, [{ field: 'email', message: 'Email already registered' }]);
+  }
+
+  // Create user
+  const passwordHash = await hashPassword(password);
+  const user = await createUser(ctx.db, {
+    email,
+    password_hash: passwordHash,
+    display_name,
+  });
+
+  // Create tokens
+  const accessToken = await createAccessToken(user.id, ctx.jwtSecret);
+  const refreshToken = await createRefreshToken(user.id, ctx.jwtSecret);
+  const refreshTokenHash = await sha256(refreshToken);
+  const { refreshToken: refreshExpiry } = getTokenExpiry();
+
+  // Store refresh token
+  await createRefreshTokenDb(ctx.db, {
+    user_id: user.id,
+    token_hash: refreshTokenHash,
+    expires_at: new Date(Date.now() + refreshExpiry * 1000).toISOString(),
+    user_agent: ctx.request.headers.get('User-Agent') ?? undefined,
+    ip_address: ctx.request.headers.get('CF-Connecting-IP') ?? undefined,
+  });
+
+  const response: AuthResponse = {
+    user: toUserPublic(user),
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    expires_in: getTokenExpiry().accessToken,
+  };
+
+  return jsonResponse(response, 201);
+}
+
+/**
+ * POST /auth/login
+ */
+export async function handleLogin(ctx: HandlerContext): Promise<Response> {
+  const body = await ctx.request.json();
+  const parsed = LoginRequestSchema.safeParse(body);
+
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((i) => ({
+      field: i.path.join('.'),
+      message: i.message,
+    }));
+    return errorResponse('Validation failed', 'ERR_VALIDATION', 422, details);
+  }
+
+  const { email, password } = parsed.data;
+
+  // Find user
+  const user = await getUserByEmail(ctx.db, email);
+  if (!user) {
+    return errorResponse('Invalid email or password', 'ERR_INVALID_CREDENTIALS', 401);
+  }
+
+  // Verify password
+  const valid = await verifyPassword(password, user.password_hash);
+  if (!valid) {
+    return errorResponse('Invalid email or password', 'ERR_INVALID_CREDENTIALS', 401);
+  }
+
+  // Update last login
+  await updateUserLastLogin(ctx.db, user.id);
+
+  // Create tokens
+  const accessToken = await createAccessToken(user.id, ctx.jwtSecret);
+  const refreshToken = await createRefreshToken(user.id, ctx.jwtSecret);
+  const refreshTokenHash = await sha256(refreshToken);
+  const { refreshToken: refreshExpiry } = getTokenExpiry();
+
+  // Store refresh token
+  await createRefreshTokenDb(ctx.db, {
+    user_id: user.id,
+    token_hash: refreshTokenHash,
+    expires_at: new Date(Date.now() + refreshExpiry * 1000).toISOString(),
+    user_agent: ctx.request.headers.get('User-Agent') ?? undefined,
+    ip_address: ctx.request.headers.get('CF-Connecting-IP') ?? undefined,
+  });
+
+  const response: AuthResponse = {
+    user: toUserPublic(user),
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    expires_in: getTokenExpiry().accessToken,
+  };
+
+  return jsonResponse(response);
+}
+
+/**
+ * POST /auth/refresh
+ */
+export async function handleRefresh(ctx: HandlerContext): Promise<Response> {
+  const body = await ctx.request.json();
+  const parsed = RefreshRequestSchema.safeParse(body);
+
+  if (!parsed.success) {
+    return errorResponse('Invalid request', 'ERR_VALIDATION', 422);
+  }
+
+  const { refresh_token } = parsed.data;
+
+  // Verify JWT
+  const payload = await verifyJwt(refresh_token, ctx.jwtSecret);
+  if (!payload || payload.type !== 'refresh') {
+    return errorResponse('Invalid refresh token', 'ERR_INVALID_TOKEN', 401);
+  }
+
+  // Check if refresh token is in database (not revoked)
+  const refreshTokenHash = await sha256(refresh_token);
+  const storedToken = await getRefreshTokenByHash(ctx.db, refreshTokenHash);
+  if (!storedToken) {
+    return errorResponse('Refresh token has been revoked', 'ERR_TOKEN_REVOKED', 401);
+  }
+
+  // Get user
+  const user = await getUserById(ctx.db, payload.sub);
+  if (!user) {
+    return errorResponse('User not found', 'ERR_USER_NOT_FOUND', 404);
+  }
+
+  // Revoke old refresh token
+  await revokeRefreshToken(ctx.db, storedToken.id);
+
+  // Create new tokens
+  const accessToken = await createAccessToken(user.id, ctx.jwtSecret);
+  const newRefreshToken = await createRefreshToken(user.id, ctx.jwtSecret);
+  const newRefreshTokenHash = await sha256(newRefreshToken);
+  const { refreshToken: refreshExpiry } = getTokenExpiry();
+
+  // Store new refresh token
+  await createRefreshTokenDb(ctx.db, {
+    user_id: user.id,
+    token_hash: newRefreshTokenHash,
+    expires_at: new Date(Date.now() + refreshExpiry * 1000).toISOString(),
+    user_agent: ctx.request.headers.get('User-Agent') ?? undefined,
+    ip_address: ctx.request.headers.get('CF-Connecting-IP') ?? undefined,
+  });
+
+  const response: AuthResponse = {
+    user: toUserPublic(user),
+    access_token: accessToken,
+    refresh_token: newRefreshToken,
+    expires_in: getTokenExpiry().accessToken,
+  };
+
+  return jsonResponse(response);
+}
+
+/**
+ * POST /auth/logout
+ */
+export async function handleLogout(ctx: HandlerContext, authContext: AuthContext): Promise<Response> {
+  // Revoke all refresh tokens for user
+  await revokeAllUserRefreshTokens(ctx.db, authContext.userId);
+
+  return jsonResponse({ message: 'Logged out successfully' });
+}
+
+/**
+ * GET /auth/me
+ */
+export async function handleGetMe(ctx: HandlerContext, authContext: AuthContext): Promise<Response> {
+  const user = await getUserById(ctx.db, authContext.userId);
+  if (!user) {
+    return errorResponse('User not found', 'ERR_USER_NOT_FOUND', 404);
+  }
+
+  const response: UserResponse = toUserPublic(user);
+  return jsonResponse(response);
+}
+
+/**
+ * PUT /auth/me
+ */
+export async function handleUpdateMe(ctx: HandlerContext, authContext: AuthContext): Promise<Response> {
+  const body = await ctx.request.json();
+  const parsed = UpdateProfileRequestSchema.safeParse(body);
+
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((i) => ({
+      field: i.path.join('.'),
+      message: i.message,
+    }));
+    return errorResponse('Validation failed', 'ERR_VALIDATION', 422, details);
+  }
+
+  await updateUserProfile(ctx.db, authContext.userId, parsed.data);
+
+  const user = await getUserById(ctx.db, authContext.userId);
+  if (!user) {
+    return errorResponse('User not found', 'ERR_USER_NOT_FOUND', 404);
+  }
+
+  const response: UserResponse = toUserPublic(user);
+  return jsonResponse(response);
+}
+
+/**
+ * PUT /auth/password
+ */
+export async function handleChangePassword(ctx: HandlerContext, authContext: AuthContext): Promise<Response> {
+  const body = await ctx.request.json();
+  const parsed = ChangePasswordRequestSchema.safeParse(body);
+
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((i) => ({
+      field: i.path.join('.'),
+      message: i.message,
+    }));
+    return errorResponse('Validation failed', 'ERR_VALIDATION', 422, details);
+  }
+
+  const { current_password, new_password } = parsed.data;
+
+  // Validate new password strength
+  const passwordError = validatePasswordStrength(new_password);
+  if (passwordError) {
+    return errorResponse(passwordError, 'ERR_WEAK_PASSWORD', 422, [{ field: 'new_password', message: passwordError }]);
+  }
+
+  // Get user
+  const user = await getUserById(ctx.db, authContext.userId);
+  if (!user) {
+    return errorResponse('User not found', 'ERR_USER_NOT_FOUND', 404);
+  }
+
+  // Verify current password
+  const valid = await verifyPassword(current_password, user.password_hash);
+  if (!valid) {
+    return errorResponse('Current password is incorrect', 'ERR_INVALID_PASSWORD', 401, [{ field: 'current_password', message: 'Current password is incorrect' }]);
+  }
+
+  // Update password
+  const newPasswordHash = await hashPassword(new_password);
+  await updateUserPassword(ctx.db, authContext.userId, newPasswordHash);
+
+  // Revoke all refresh tokens (force re-login)
+  await revokeAllUserRefreshTokens(ctx.db, authContext.userId);
+
+  return jsonResponse({ message: 'Password changed successfully. Please login again.' });
+}

package/src/auth/jwt.ts

@@ -0,0 +1,112 @@
+// JWT utilities using Web Crypto API (HS256)
+
+import { base64UrlEncode, base64UrlDecode } from '../utils/crypto';
+
+export interface JwtPayload {
+  sub: string; // user_id
+  iat: number; // issued at (unix timestamp)
+  exp: number; // expires at (unix timestamp)
+  type: 'access' | 'refresh';
+}
+
+const JWT_ALGORITHM = 'HS256';
+const ACCESS_TOKEN_EXPIRY = 15 * 60; // 15 minutes
+const REFRESH_TOKEN_EXPIRY = 7 * 24 * 60 * 60; // 7 days
+
+/**
+ * Sign a JWT using HS256
+ */
+export async function signJwt(payload: JwtPayload, secret: string): Promise<string> {
+  const header = { alg: JWT_ALGORITHM, typ: 'JWT' };
+  const encodedHeader = base64UrlEncode(JSON.stringify(header));
+  const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+
+  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+
+  const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`));
+
+  return `${encodedHeader}.${encodedPayload}.${base64UrlEncode(signature)}`;
+}
+
+/**
+ * Verify and decode a JWT
+ * Returns null if invalid or expired
+ */
+export async function verifyJwt(token: string, secret: string): Promise<JwtPayload | null> {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    return null;
+  }
+
+  const [encodedHeader, encodedPayload, encodedSignature] = parts;
+
+  // Verify signature
+  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+
+  // Decode signature from base64url
+  const signatureStr = base64UrlDecode(encodedSignature);
+  const signature = new Uint8Array(signatureStr.length);
+  for (let i = 0; i < signatureStr.length; i++) {
+    signature[i] = signatureStr.charCodeAt(i);
+  }
+
+  const valid = await crypto.subtle.verify('HMAC', key, signature, new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`));
+
+  if (!valid) {
+    return null;
+  }
+
+  // Decode and parse payload
+  try {
+    const payloadStr = base64UrlDecode(encodedPayload);
+    const payload = JSON.parse(payloadStr) as JwtPayload;
+
+    // Check expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp < now) {
+      return null;
+    }
+
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create an access token
+ */
+export async function createAccessToken(userId: string, secret: string): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  const payload: JwtPayload = {
+    sub: userId,
+    iat: now,
+    exp: now + ACCESS_TOKEN_EXPIRY,
+    type: 'access',
+  };
+  return signJwt(payload, secret);
+}
+
+/**
+ * Create a refresh token
+ */
+export async function createRefreshToken(userId: string, secret: string): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  const payload: JwtPayload = {
+    sub: userId,
+    iat: now,
+    exp: now + REFRESH_TOKEN_EXPIRY,
+    type: 'refresh',
+  };
+  return signJwt(payload, secret);
+}
+
+/**
+ * Get token expiry times
+ */
+export function getTokenExpiry(): { accessToken: number; refreshToken: number } {
+  return {
+    accessToken: ACCESS_TOKEN_EXPIRY,
+    refreshToken: REFRESH_TOKEN_EXPIRY,
+  };
+}