feat(users): GET /v4/users/by-identity + projectName on signatures (EasyCLA M1)

[mlehotskylf]

What

Two upstream reads that the EasyCLA → LFX Self Serve Milestone-1 "My CLAs" integration needs (Self Serve PR: linuxfoundation/lfx-self-serve#1203). Read-only, no schema changes, no writes.

1. GET /v4/users/by-identity?lfUsername=…&email=…&githubId=…

Resolves the union of EasyCLA user records matching ANY supplied identity key — LF username, verified email(s), or linked GitHub numeric ID(s) — deduped by user_id, empty array on no match. This lets Self Serve map one logged-in identity to its one-or-more EasyCLA records (including pre-LF-login GitHub-derived history).

• Union logic lives in the v1 users.Service (GetUsersByIdentity), reusing existing GSI-backed lookups (lf-username-index, lf-email-index, github-id-index) — no table scans.
• v2/users handler is thin request/response translation (v1→v2 model copy), mirroring v2/current_user.
• Router: the path is not in the cla-service public allow-list (lfx-gateway/dynamic/services/cla-service.yaml), so it lands on the secured router. Self Serve remains the authorization boundary.
• 6 unit tests (union / dedupe / skip-on-lookup-error / blank-key / empty-input / empty-user-id).

Known limitation (documented): email matching is against the primary lf_email GSI only. A verified email present solely in a user's secondary user_emails list is not resolved — that would require a table scan, which is unsuitable per-request. Username + GitHub ID + primary email cover the common cases.

2. projectName on the signature response

GET /v4/signatures/user/{userID} now returns each signature's CLA-Group display name (previously only the CLA-Group ID / projectID was available). Added projectName to swagger/common/signature.yaml; the v2 handler resolves it from the CLA Group, cached per distinct project ID per request, best-effort (a miss leaves it empty and never fails the listing).

Testing

make fmt && go build ./... && go test (users, v2/signatures, cmd) && make lint — all green. gen/ is gitignored; regenerate with make swagger.

Notes

• Fits the spec's "at most one small read endpoint, no schema changes" boundary (spec: docs(easycla-ss): EasyCLA → Self Serve migration architecture docs #5124, tasks T007–T010a).
• The no-ownership-check caveat that applies to GET /v4/signatures/user/{userID} applies here too — treat as an internal/service API; the caller is the authorization boundary.

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

Adds a v2 users-by-identity endpoint backed by normalized, deduplicated lookups across usernames, emails, and GitHub IDs. Signature responses now include resolvable CLA Group display names through cached enrichment.

Changes

Identity Lookup API

Layer / File(s)	Summary
Identity resolution contract and implementation cla-backend-go/swagger/cla.v2.yaml, cla-backend-go/users/service.go, cla-backend-go/users/service_identity_test.go, cla-backend-go/cmd/refresh_stored_username_test.go	Defines the identity lookup endpoint and service method, resolves matching users across identity types, deduplicates results, skips blank keys, and continues past individual lookup failures.
v2 handler registration and response mapping cla-backend-go/v2/users/handlers.go, cla-backend-go/cmd/server.go, cla-backend-go/v2/signatures/mock_users/mock_service.go	Registers the v2 route, propagates request and auth context, converts v1 users to v2 users, and adds generated service mocks.

Signature Project Name Enrichment

Layer / File(s)	Summary
Signature schema and CLA Group enrichment cla-backend-go/swagger/common/signature.yaml, cla-backend-go/v2/signatures/handlers.go	Adds projectName to the signature schema and fills missing values from cached CLA Group lookups without failing the signature request.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant UsersHandler
  participant UsersService
  Client->>UsersHandler: GET /users/by-identity
  UsersHandler->>UsersService: GetUsersByIdentity(...)
  UsersService->>UsersService: Query username, emails, and GitHub IDs
  UsersService-->>UsersHandler: Deduplicated user list
  UsersHandler-->>Client: OK response with v2 users

Loading

Suggested labels: do-not-merge, WIP

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% 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 names the new users-by-identity endpoint and the signature projectName addition, matching the main changes.
Description check	✅ Passed	The description accurately describes both the new users-by-identity read endpoint and projectName on signatures.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/users-by-identity

---

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

[Copilot]

Pull request overview

Adds identity-based user resolution and CLA-group display names for the Self Serve “My CLAs” integration.

Changes:

• Adds the secured /v4/users/by-identity endpoint with GSI-backed union and deduplication.
• Enriches user signatures with cached CLA-group names.
• Adds service tests and updates wiring and mocks.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cla-backend-go/v2/users/handlers.go	Implements v2 endpoint translation.
cla-backend-go/v2/signatures/mock_users/mock_service.go	Regenerates the users-service mock.
cla-backend-go/v2/signatures/handlers.go	Adds signature project-name enrichment.
cla-backend-go/users/service.go	Implements identity union logic.
cla-backend-go/users/service_identity_test.go	Tests identity resolution behavior.
cla-backend-go/swagger/common/signature.yaml	Defines projectName.
cla-backend-go/swagger/cla.v2.yaml	Defines the identity endpoint.
cla-backend-go/cmd/server.go	Registers the v2 users handler.
cla-backend-go/cmd/refresh_stored_username_test.go	Updates the users-service test stub.

Files not reviewed (1)

• cla-backend-go/v2/signatures/mock_users/mock_service.go: Generated file

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (2)

cla-backend-go/swagger/cla.v2.yaml (1)

2775-2790: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Bound the email/githubId arrays to avoid request amplification.

Each array element triggers a separate GSI lookup in GetUsersByIdentity (service layer). Without a maxItems cap, a caller can submit an arbitrarily large array and multiply downstream DynamoDB calls per request.

♻️ Proposed fix

         - name: email
           description: verified email address(es) to match; repeatable
           in: query
           type: array
           items:
             type: string
           collectionFormat: multi
           required: false
+          maxItems: 25
         - name: githubId
           description: linked GitHub numeric ID(s) to match; repeatable
           in: query
           type: array
           items:
             type: string
           collectionFormat: multi
           required: false
+          maxItems: 25

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cla-backend-go/swagger/cla.v2.yaml` around lines 2775 - 2790, Update the
email and githubId array parameter definitions in the Swagger schema to include
a maxItems constraint, using the service layer’s supported lookup bound for both
fields. Keep their existing repeatable multi-value query behavior unchanged.

cla-backend-go/v2/users/handlers.go (1)

24-61: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a handler-level unit test for the new Configure wiring.

Only service-level tests (service_identity_test.go) exist; the v2→v1 mapping, empty-result path, and error responses (GetUsersByIdentityInternalServerError) in this handler aren't directly exercised.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cla-backend-go/v2/users/handlers.go` around lines 24 - 61, Add handler-level
unit tests for Configure and its GetUsersByIdentityHandler wiring, covering
v2-to-v1 user mapping, empty service results, and service or copier failures
returning GetUsersByIdentityInternalServerError responses with the expected
request ID and error payload.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cla-backend-go/swagger/common/signature.yaml`:
- Around line 82-84: Add x-omitempty: false to the projectName schema property
in signature.yaml so unresolved signatures serialize projectName as an empty
string instead of omitting the field.

In `@cla-backend-go/users/service.go`:
- Around line 208-213: The GetUsersByIdentity logging must not emit raw identity
values. Remove or replace the lfUsername field and per-item Debugf calls at the
referenced points with non-PII information such as counts or consistent hashes,
preserving useful debugging context without logging email addresses or other raw
identifiers.
- Around line 232-250: Remove the GetUserByEmail call from this email loop and
retain the GetUsersByLFEmail lookup, including its existing error handling and
add() iteration. Leave the email normalization and deduplication behavior
unchanged.

---

Nitpick comments:
In `@cla-backend-go/swagger/cla.v2.yaml`:
- Around line 2775-2790: Update the email and githubId array parameter
definitions in the Swagger schema to include a maxItems constraint, using the
service layer’s supported lookup bound for both fields. Keep their existing
repeatable multi-value query behavior unchanged.

In `@cla-backend-go/v2/users/handlers.go`:
- Around line 24-61: Add handler-level unit tests for Configure and its
GetUsersByIdentityHandler wiring, covering v2-to-v1 user mapping, empty service
results, and service or copier failures returning
GetUsersByIdentityInternalServerError responses with the expected request ID and
error payload.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bb9da78f-0141-4a3b-9903-d3798695217d

📥 Commits

Reviewing files that changed from the base of the PR and between f9cc184 and d221c3c.

📒 Files selected for processing (9)

• cla-backend-go/cmd/refresh_stored_username_test.go
• cla-backend-go/cmd/server.go
• cla-backend-go/swagger/cla.v2.yaml
• cla-backend-go/swagger/common/signature.yaml
• cla-backend-go/users/service.go
• cla-backend-go/users/service_identity_test.go
• cla-backend-go/v2/signatures/handlers.go
• cla-backend-go/v2/signatures/mock_users/mock_service.go
• cla-backend-go/v2/users/handlers.go

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

cla-backend-go/users/service.go (1)

233-241: 🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

Deduplicate normalized keys before querying the repository.

add deduplicates returned users, but duplicate or normalization-equivalent emails and GitHub IDs still trigger repeated sequential repository reads. Deduplicate normalized keys before each loop to avoid unnecessary DynamoDB I/O and latency.

Proposed fix

+	seenEmails := make(map[string]struct{}, len(emails))
 	for _, email := range emails {
 		email = strings.ToLower(strings.TrimSpace(email))
 		if email == "" {
 			continue
 		}
+		if _, seen := seenEmails[email]; seen {
+			continue
+		}
+		seenEmails[email] = struct{}{}

+	seenGitHubIDs := make(map[string]struct{}, len(githubIDs))
 	for _, githubID := range githubIDs {
 		githubID = strings.TrimSpace(githubID)
 		if githubID == "" {
 			continue
 		}
+		if _, seen := seenGitHubIDs[githubID]; seen {
+			continue
+		}
+		seenGitHubIDs[githubID] = struct{}{}

Also applies to: 249-255

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cla-backend-go/users/service.go` around lines 233 - 241, Deduplicate the
normalized email keys before the email loop in the user lookup flow, and
likewise deduplicate normalized GitHub ID keys before the corresponding loop.
Update the logic around GetUsersByLFEmail and the analogous GitHub-ID repository
query so each unique key is queried at most once while preserving the existing
user aggregation behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@cla-backend-go/users/service.go`:
- Around line 233-241: Deduplicate the normalized email keys before the email
loop in the user lookup flow, and likewise deduplicate normalized GitHub ID keys
before the corresponding loop. Update the logic around GetUsersByLFEmail and the
analogous GitHub-ID repository query so each unique key is queried at most once
while preserving the existing user aggregation behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7411fe78-89eb-4275-88fa-5df2c9244f49

📥 Commits

Reviewing files that changed from the base of the PR and between d221c3c and e804728.

📒 Files selected for processing (2)

• cla-backend-go/users/service.go
• cla-backend-go/users/service_identity_test.go

🚧 Files skipped from review as they are similar to previous changes (1)

• cla-backend-go/users/service_identity_test.go

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• cla-backend-go/v2/signatures/mock_users/mock_service.go: Generated file

Comments suppressed due to low confidence (7)

cla-backend-go/users/service.go:206

• The implementation below treats every repository error as a normal miss. GetUserByLFUserName only returns errors for expression/DynamoDB/unmarshal failures, while the email and GitHub methods mix not-found errors with operational failures. A throttled or unavailable GSI can therefore produce a successful but incomplete/empty response, and the handler's 500 path is effectively unreachable. Skip only recognized not-found results and propagate operational failures so callers can retry instead of silently losing CLA history.

// A lookup that fails or finds nothing for one key is logged and skipped, not fatal: this is a
// "match any" resolver, so one missing key must not fail the others. Returns an empty (non-nil)
// slice when nothing matches.

cla-backend-go/v2/users/handlers.go:33

• This field persists the supplied LF username in every handler log even though users/service.go:208-209 explicitly classifies identity values as PII and avoids logging them. Record only whether the key was supplied, as is already done for the array parameters.

				"lfUsername":     utils.StringValue(params.LfUsername),

cla-backend-go/swagger/cla.v2.yaml:2781

• These identity values are placed in the query string, while cmd/server.go:908 logs r.URL.String() for every request. Verified emails, LF usernames, and GitHub IDs will therefore be persisted in application logs regardless of the handler's own structured fields. Redact these query parameters in request logging (and verify gateway access-log redaction), or use a request body for this internal lookup.

        - name: email
          description: verified email address(es) to match; repeatable
          in: query
          type: array
          items:
            type: string
          collectionFormat: multi

cla-backend-go/users/service.go:240

• The linked M1 contract and FR-005 require resolving verified emails, including matches in user_emails, but this deliberately queries only primary lf_email. A user whose verified address exists only in the secondary list will miss that EasyCLA record and its CLA history, so the integration cannot meet its stated completeness criterion. Add an indexed secondary-email lookup, or update the linked contract/acceptance criteria to explicitly accept this limitation before merging.

		// lf-email-index is keyed on lf_email; GetUsersByLFEmail queries that GSI (no scan) and
		// returns every match, so it fully covers GetUserByEmail (same query, first-result-only).
		if us, err := s.repo.GetUsersByLFEmail(email); err != nil {

cla-backend-go/v2/signatures/handlers.go:711

• claGroupService.GetCLAGroupByID always requests LoadRepoDetails (project/service/service.go:78-105), which launches GitHub and Gerrit repository lookups in addition to DynamoDB (project/repository/repository.go:875-905). Doing that once per distinct signature project is unnecessary for a name-only enrichment and can substantially increase latency and failure exposure. Use the already-injected repository with DontLoadRepoDetails.

				if claGroupModel, cgErr := claGroupService.GetCLAGroupByID(ctx, sig.ProjectID); cgErr != nil || claGroupModel == nil {

cla-backend-go/swagger/cla.v2.yaml:2781

• This repeatable array has no maxItems, so one authenticated request can trigger an unbounded number of sequential DynamoDB email-index queries in GetUsersByIdentity. Add a small contract-level limit (and ideally deduplicate normalized values before lookup) to bound Lambda duration and read cost.

          type: array
          items:
            type: string
          collectionFormat: multi

cla-backend-go/swagger/cla.v2.yaml:2789

• This array is also unbounded, and each value causes a sequential GitHub-ID GSI query. Add maxItems plus a numeric item pattern/length bound so malformed or oversized requests are rejected before consuming arbitrary DynamoDB reads.

          type: array
          items:
            type: string
          collectionFormat: multi

[mlehotskylf]

Review Feedback Addressed

Commit: e804728

Changes Made

• users/service.go: dropped the redundant GetUserByEmail call in GetUsersByIdentity — it hits the same lf-email-index (identical key/index/projection, first-result-only) as GetUsersByLFEmail, so calling both doubled DynamoDB reads per email for zero added coverage (per copilot[bot], coderabbitai)
• users/service.go: trim whitespace-only lfUsername before the GSI lookup, matching the email/githubID handling (per copilot[bot])
• users/service.go: keep PII (LF username, raw emails) out of the persistent log fields and per-key miss logs; counts only (per coderabbitai)
• users/service_identity_test.go: updated expectations for the removed call and added whitespace-username coverage

Declined

• service.go:206 — errors treated as no-match: this is the intended documented "match any" behavior (one key's failure must not fail the union); fail-closed-on-outage would be a separate deliberate design change (flagged by copilot[bot])
• cla.v2.yaml:2788 — non-numeric github IDs safely no-match via the index; correct "not found" outcome, not a bug (flagged by copilot[bot])
• signature.yaml:84 — trivial swagger style nitpick; consistent with surrounding fields (flagged by coderabbitai)

Threads Resolved

5 of 5 unresolved threads addressed.

[mlehotskylf]

We no longer need this as @lukaszgryglicki implemented this endpoint and this was only for testing.