POST /project/:id/tool returns 500

[thehabes]

Bug Report

Severity: Critical
Found during: Pre-production stack test (2026-03-26)
Endpoint: POST /project/:projectId/tool

Description

Adding a tool to a project crashes with a 500 error. The server attempts to access .enabled on an undefined object.

Steps to Reproduce

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Test Tool","toolName":"test-tool","url":"https://example.com/tool","location":"sidebar"}' \
  "https://dev.api.t-pen.org/project/<PROJECT_ID>/tool"

Expected

200 with tool added to project.

Actual

{"status":500,"message":"Cannot read properties of undefined (reading 'enabled')"}

Analysis

The tool creation handler in projectToolsRouter.js accesses .enabled on an undefined object. Likely the project's tools configuration is not initialized before the property access. This blocks all tool management (add, toggle, remove) since toggle and remove depend on a tool having been added.

Impact

The Interfaces project-tools component cannot add, toggle, or remove tools from projects. All three tool endpoints (POST /tool, PUT /toggleTool, DELETE /tool) are effectively broken.

Environment

• Stack: dev.api.t-pen.org
• Tested with a freshly imported project (from IIIF v3 manifest)
• Auth: valid Auth0 JWT

[thehabes]

Investigation Update

The endpoint works correctly when called the way Interfaces actually calls it. The 500 only occurs with an incomplete request body.

Root cause: The server reads custom.enabled from the request body without checking if custom exists first. When the custom object is missing, it crashes with "Cannot read properties of undefined (reading 'enabled')".

What Interfaces sends (from project-tools/index.js:329-345):

{
  "label": "Test Tool",
  "toolName": "test-tool",
  "url": "https://example.com/tool",
  "location": "pane",
  "custom": { "enabled": true, "tagName": "" }
}

This succeeds with 200. ✓

What the test sent (missing custom):

{
  "label": "Test Tool",
  "toolName": "test-tool",
  "url": "https://example.com/tool",
  "location": "sidebar"
}

This crashes with 500. ✗

Downgrading severity from Critical to Minor. Users won't hit this in practice since the Interfaces component always sends the custom object. However, the server should still validate the input and return 400 instead of crashing with 500 — any direct API consumer or future client could omit it.

Suggested fix: Add a guard in projectToolsRouter.js before accessing custom.enabled:

if (!req.body.custom || typeof req.body.custom.enabled !== 'boolean') {
  return respondWithError(res, 400, "Missing required field: custom.enabled")
}