[CSM Integration Service] Add new Go service for third-party account/project search

[Hesara2003]

Purpose

Third-party (M2M) consumers need a way to search accounts and projects (and their contacts) without going through the CSM Portal's own end-user-facing backend. This adds a new, standalone service scoped to exactly that.

Scope note: Inbound auth is intentionally out of scope for this service's own code — it's fronted by Choreo's API Manager gateway (subscription + client-credentials M2M app auth), which owns that trust boundary. See CLAUDE.md in the new service for the full rationale.

Goals

• Expose account search, project search, and a contacts sub-resource for both, to third-party M2M consumers
• Authenticate outbound to the entity service via OAuth2 client credentials (M2M), with no end-user identity of its own
• Optionally forward a caller-supplied x-user-id-token, for consumers that need entity-service's ServiceNow-backed operations (which require a forwarded end-user identity and reject M2M-only requests)

Approach

• New top-level Go module at operations/csm-integration-service, modeled on apps/csm-portal/backend's entity-client/handler pattern (internal/entity, internal/handler, internal/middleware), stripped of end-user JWT concerns since this service has a different consumer/trust model
• Raw []byte JSON passthrough — no reshaping of upstream responses, matching this backend family's convention
• Middleware chain: SecurityHeaders → CorrelationID → UserIDToken → Logger. Correlation IDs are tagged with a cis- prefix (generated or forwarded) so logs are easy to trace back to this service
• openapi.yaml scoped to the 6 real endpoints + /health, published as the contract for Choreo's Developer Portal

User stories

As a third-party integrator, I can search accounts and projects (and their contacts) through a dedicated M2M API, without needing any CSM Portal end-user credentials.

Release note

Added a new service, CSM Integration Service, exposing account/project search and contacts to third-party M2M consumers.

Documentation

N/A — openapi.yaml and CLAUDE.md in the new service directory are the primary docs; no external doc surface affected yet.

Automation tests

• Unit tests: 22 tests across internal/entity (86% coverage), internal/handler (93.1%), internal/middleware (79.5%) — OAuth2 client-credentials flow, upstream error mapping/truncation, correlation ID generation/prefixing, optional x-user-id-token pass-through, full request validation (path params, body size, JSON shape)
• Verified against staging: exercised the full chain (this service → entity-service → ServiceNow-backed path) with real staging credentials; confirmed account/project search and both contacts endpoints return real data end-to-end

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? yes
• Ran FindSecurityBugs plugin and verified report? N/A (Go service — ran gosec instead, 0 issues; see README.md)
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes

Test environment

• go vet ./..., go build ./..., go test -race ./... all passing locally (Go 1.26)

Summary by CodeRabbit

• New Features
  • Added the CSM Integration Service with /health, account, project, and contact-search endpoints.
  • Enabled OAuth2 client-credentials for upstream access and optional x-user-id-token pass-through.
  • Added correlation IDs, request logging, security response headers, and standardized JSON error responses.
• Documentation
  • Added service README, configuration example, detailed integration documentation, and a complete OpenAPI specification.
• Tests
  • Added unit tests covering middleware, handler validation/error mapping, and the upstream entity client.

[coderabbitai]

Warning

Review limit reached

@Hesara2003, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 11 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fa264691-3000-49e3-9466-ece274beb3cc

📥 Commits

Reviewing files that changed from the base of the PR and between b038a83 and f020695.

📒 Files selected for processing (3)

• operations/csm-integration-service/.env.example
• operations/csm-integration-service/README.md
• operations/csm-integration-service/cmd/server/main.go

📝 Walkthrough

Walkthrough

Adds a Go CSM Integration Service exposing account and project APIs, forwarding requests to an OAuth2-authenticated entity service with correlation and optional user-token propagation, standardized validation and error handling, middleware, OpenAPI definitions, configuration, documentation, and tests.

Changes

CSM Integration Service

Layer / File(s)	Summary
API contract and service setup operations/csm-integration-service/openapi.yaml, operations/csm-integration-service/README.md, operations/csm-integration-service/CLAUDE.md, operations/csm-integration-service/.env.example, operations/csm-integration-service/.choreo/*, operations/csm-integration-service/go.mod, README.md	Defines account/project and contacts endpoints, schemas, OAuth2 configuration, environment placeholders, Choreo registration, documentation, and development conventions.
Runtime bootstrap and lifecycle operations/csm-integration-service/cmd/server/main.go, operations/csm-integration-service/Makefile	Loads configuration, constructs clients and handlers, registers routes and middleware, serves HTTP traffic, and performs graceful shutdown.
Authenticated entity-service transport operations/csm-integration-service/internal/apierror/*, operations/csm-integration-service/internal/entity/*	Adds OAuth2 client-credentials requests, raw JSON passthrough, upstream error conversion, URL-escaped resource methods, correlation propagation, optional user-token forwarding, and transport tests.
Account and project HTTP handlers operations/csm-integration-service/internal/handler/*	Adds validation, request-size limits, upstream delegation, standardized error mapping, JSON responses, mocks, and handler tests.
Request context and response middleware operations/csm-integration-service/internal/middleware/*	Adds correlation IDs, structured request logging, security headers, optional user-token propagation, and middleware tests.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant CSMIntegrationService
  participant EntityClient
  participant OAuth2TokenEndpoint
  participant EntityService
  Client->>CSMIntegrationService: Send account or project request
  CSMIntegrationService->>EntityClient: Validate and delegate with request context
  EntityClient->>OAuth2TokenEndpoint: Request client-credentials token
  OAuth2TokenEndpoint-->>EntityClient: Return access token
  EntityClient->>EntityService: Forward authenticated request
  EntityService-->>EntityClient: Return JSON or upstream error
  EntityClient-->>CSMIntegrationService: Return response bytes or mapped error
  CSMIntegrationService-->>Client: Return JSON response

Loading

Possibly related PRs

• wso2-open-operations/cs-tools#1191: Adds overlapping account and project contacts-search endpoints and client methods.
• wso2-open-operations/cs-tools#1196: Adds the related optional x-user-id-token forwarding behavior.
• wso2-open-operations/cs-tools#911: Adds the related SecurityHeaders middleware and tests.

Suggested labels: Type/Improvement, Area/Backend, Platform/Web

Suggested reviewers: cloby99, rksk, rashmika998

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main change: adding a new Go service for third-party account and project search.
Description check	✅ Passed	The description covers purpose, goals, approach, user stories, release note, docs, tests, security, and environment.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Rashmika998]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[s-sandali]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.