Add config.api_authenticate hook for custom API auth

[HamptonMakes]

Problem

The API controllers only support Bearer token authentication. Host apps like coplan-square that have their own auth infrastructure (e.g., Trogdor mTLS) need a way to use it for API calls too — so agents can use sq curl instead of managing separate API tokens.

Solution

Add config.api_authenticate — a hook that follows the same pattern as config.authenticate:

CoPlan.configure do |config|
  config.api_authenticate = ->(request) {
    { external_id: "123", name: "user", admin: false }
  }
end

When set, API controllers use the hook and auto-provision users (same find_or_initialize_by pattern as the web auth). When unset, Bearer token auth remains the default.

Changes

• Configuration: Added api_authenticate accessor
• Api::V1::BaseController: New authenticate_api! dispatches to hook or token auth. Added api_actor_id and api_author_type helpers so child controllers don't reference @api_token directly.
• Child controllers (leases, sessions, comments, operations): Replaced all @api_token.id / ApiToken::HOLDER_TYPE references with the new helpers.

Test results

All 389 specs passing — existing Bearer token tests still pass (hook is nil by default).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e1200c556f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Return valid actor type from api_author_type hook path

When config.api_authenticate is enabled, api_author_type returns "CoPlan::User", but API writes this value into Comment.author_type and PlanVersion.actor_type (comments_controller and operations_controller). Those fields are validated against enum constants that only allow human/local_agent/cloud_persona/system (engine/app/models/coplan/comment.rb and engine/app/models/coplan/plan_version.rb), so hook-authenticated requests will fail to create comments (422) and can fail version commits with RecordInvalid (500), effectively breaking core API editing flows for the new auth mode.

Useful? React with 👍 / 👎.

[HamptonMakes]

Good catch! Fixed — api_author_type now returns "human" for hook auth instead of "CoPlan::User". This matches the valid enum values in Comment, PlanVersion, and EditSession.