chore: big refactoring of the basic structure

[KanBen86]

Description

Please describe the changes you made.

Checklist

• Code has been tested locally
• All existing tests pass
• Changes are documented
• PR adheres to the contributing guidelines
• Reviewers have been assigned

Additional Notes

Is there anything the reviewers should pay attention to?

Generally, to fix this issue you should avoid returning raw exception messages (or stack traces) to the client. Instead, log the full exception on the server (which is already done with logger.exception(...)) and return a generic, user-safe error message with the same HTTP status code.

Concretely in app/api/routes.py:

• In the /health endpoint, replace return jsonify({"error": str(exc)}), 500 with a generic message such as return jsonify({"error": "Internal server error"}), 500 (or similar wording).
• In the /transform endpoint, likewise replace return jsonify({"error": str(exc)}), 500 with the same generic message.
• No new imports are needed; we continue using jsonify and the existing logging. Functionality is preserved in terms of status codes and metrics; only the exposed error body is made generic, while detailed information remains in server logs.

In general, to fix information exposure through exceptions, stop returning raw exception details (messages, stack traces) to the client. Log the exception (including stack trace) on the server, and send back a generic or otherwise pre-reviewed, non-sensitive error message and status code.

For this codebase, the minimal, behavior-preserving fix that addresses the CodeQL findings is confined to app/transform/main.py in post_transform:

• Keep the existing logging with exc_info=True so developers still get stack traces.
• Change the return values for:
  • KnownException to return a JSON error response containing str(e) (since it is explicitly for end users) but in a well-defined structure, not a bare string. This makes the taint less ambiguous to CodeQL and keeps behavior similar for clients that expect a message, but if you want stricter hardening you could also replace this with a generic string.
  • PrivateInternalException to return a generic error message (e.g., "An internal error has occurred.") instead of str(e), aligning with the comment that it should be “generic” to the end user.
• Also return consistent JSON for the unexpected exception path, which already uses a generic UnexpectedError message.

Concretely:

• In post_transform:
  • Replace return str(e), 400 in the KnownException handler with return jsonify({"error": str(e)}), 400.
  • Replace return str(e), 400 in the PrivateInternalException handler with return jsonify({"error": "An internal error has occurred."}), 500 (or stick with 400 if that’s required, but 500 better reflects an internal error).
  • Replace return str(UnexpectedError()), 400 with return jsonify({"error": str(UnexpectedError())}), 500 (or the appropriate status used elsewhere for generic unexpected errors).
• No changes are needed in app/api/routes.py because it already returns generic error JSON for its own exceptions, and it simply forwards whatever post_transform returns.

These changes require no new methods or external dependencies beyond what is already imported (jsonify is already imported in app/transform/main.py).

---

In general, to fix this kind of problem you should avoid returning raw exception messages or stack traces to users. Instead, log detailed errors internally and send clients a generic, non-sensitive message (optionally with a non-identifying error code) along with the appropriate HTTP status.

For this specific file, the best fix without changing observable behavior beyond the error text is:

• Keep the logger.exception(...) calls so full details (including stack trace) are logged on the server.
• Replace jsonify({"error": str(exc)}) with a generic, non-revealing message such as jsonify({"error": "Internal server error"}) (or slightly endpoint-specific wording if desired).
• Apply this change to both the /health handler (line 33) and the /transform handler (line 55) to ensure consistent behavior.

No new imports or helper methods are required; jsonify is already imported and used. The modifications are confined to app/api/routes.py in the except blocks of health and transform.