EasyCLA release

.gitignore

@@ -286,6 +286,6 @@ spans*.json
 *.dylib
 *.test
 *.out
-CLAUDE.md
 .claude/*
 /*user_emails.json
+.venv

CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+Copyright The Linux Foundation and each contributor to CommunityBridge.
+
+SPDX-License-Identifier: CC-BY-4.0
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+EasyCLA is the Linux Foundation's Contributor License Agreement service. It lets contributors sign ICLAs/CCLAs and gates GitHub PRs and Gerrit/GitLab reviews on CLA authorization. Third-party integrations: DocuSign (e-sign), DocRaptor (PDF), GitHub, Gerrit, GitLab, Auth0 (SSO), and Salesforce via the LFX Platform APIs.
+
+The frontend consoles (Project/Corporate/Contributor) live in **separate repositories** — this repo is backend-only plus supporting scripts/infra. Do not look for UI code here.
+
+## Repository Layout
+
+- `cla-backend-go/` — **primary backend**, Go. Powers `/v3` (EasyCLA v1, us-east-1) and `/v4` (EasyCLA v2, us-east-2, integrates with LFX Platform + Salesforce). Deployed as AWS Lambdas.
+- `cla-backend/` — Serverless Framework **deployment stack** (us-east-1). The Python backend has been removed; the sole application code it still owns is the API Gateway authorizer (`cla-backend/auth/main.go`, `cla-backend/auth/authorizer/`). Otherwise it deploys Go binaries built elsewhere — the `/v3` API and worker lambdas (dynamo-events, metrics, zipbuilder, gitlab-repository-check, user-subscribe) from `cla-backend-go/`, and the `/v1`/`/v2` `legacy-api-lambda` from `cla-backend-legacy/`.
+- `cla-backend-legacy/` — Go module (own `go.mod`): the Go implementation of the legacy `/v1`/`/v2` API surface (replaced the Python backend). Built as `bin/legacy-api-lambda` and deployed via `cla-backend/serverless.yml` on the original `api.*` domains. Responses carry `X-EasyCLA-Backend: cla-backend-legacy` headers; parity tooling lives under `internal/parity`.
+- `cla-sss-base/` — standalone Go module (own `go.mod`): client for the Sanctions Screening Service (SSS).
+- `scripts/`, `utils/` — operational shell/Python scripts (data audits, DynamoDB manipulation, deploys, credential rotation). Many `utils/*.sh` scripts operate directly against AWS environments.
+- `infra/` — infrastructure config.
+- `tests/` — functional/REST tests, Postman collections, py2go comparison tests.
+
+## Go Backend (cla-backend-go) — Primary Workflow
+
+Requires Go 1.25+. All commands run from `cla-backend-go/`.
+
+```bash
+make setup          # one-time: install swagger, golangci-lint, goimports; sets up swagger venv
+make swagger        # regenerate API models/clients from swagger specs into gen/ (see below)
+make build-mac      # build local binary -> bin/cla-mac (build-linux for Linux)
+make test           # go test -v ./... with coverage
+make lint           # golangci-lint (v1.64.8, config .golangci.yaml) + license header check
+make fmt            # gofmt + goimports
+make mock           # regenerate mocks via tools/regenmocks.sh
+make all-mac        # full pipeline: clean swagger deps fmt build test lint (all-linux on Linux)
+```
+
+Run a single test: `go test -v ./signatures/ -run TestName`
+
+Run locally (points at a real AWS environment — see below): build, set env, then `./bin/cla-mac` (from `make build-mac`) or `./bin/cla` (from `make build-linux`). Health checks at `http://localhost:8080/v3/ops/health` and `/v4/ops/health`. Set `GH_ORG_VALIDATION=false` to bypass GitHub auth checks for local curl/Postman testing.
+
+### Swagger code generation (important)
+
+The API is **swagger-first**. `gen/` is fully generated and is deleted/rebuilt by `make swagger` — never hand-edit files under `gen/`. Source specs are multi-file YAML under `swagger/` (`cla.v1.yaml`, `cla.v2.yaml`) compiled via `swagger/multi-file-swagger.py`. `make swagger` also downloads and generates clients for external LFX platform services (project-service, organization-service, user-service, acs-service) from their live dev swagger endpoints, so it requires network access. After changing an endpoint's spec, regenerate before implementing handlers.
+
+### Module architecture pattern
+
+Domain feature modules (e.g. `signatures/`, `approval_list/`, `company/`, `project/`, and most packages under `v2/`) follow a consistent three-layer split, though a module omits a layer it doesn't need (e.g. `v2/health` is handler-only, `v2/project-service` is a generated client with no handlers/service/repository):
+
+- `handlers.go` — a `Configure(api, service, ...)` function that wires generated swagger operations to service calls. Handlers do request/response translation only.
+- `service.go` — business logic, defined behind an interface; the unit-testable layer.
+- `repository.go` — DynamoDB access. `dbmodels.go` holds table row structs; `converters.go` maps between DB models, generated API models, and internal models.
+- `mocks/` — generated mocks (regenerate with `make mock`, don't edit by hand).
+
+`v2/` packages are the newer LFX-Platform-integrated implementations; top-level packages are v1/legacy. Both are wired together in `cmd/server.go`.
+
+`cmd/` holds `main.go` entrypoints for the many Lambda binaries (metrics, dynamo-events, zipbuilder, gitlab-repository-check, user-subscribe, etc.) plus the main API server (`cmd/server.go`, `cmd/server_standalone.go`, `cmd/server_aws_lambda.go`). Config is loaded from SSM via the `init` + `config` + `token` packages at startup.
+
+## Legacy Go Backend (cla-backend-legacy)
+
+Serves the legacy `/v1`/`/v2` API surface (the Python backend it replaced is gone). From the repo root:
+
+```bash
+source setenv.sh
+cd cla-backend-legacy
+go mod tidy
+make lambdas        # build deployment artifact bin/legacy-api-lambda
+STAGE=dev ADDR=":5000" make run-local   # run locally on :5000 pointing at dev environment
+```
+
+Health check: `http://localhost:5000/v2/health` (response includes `X-EasyCLA-Backend: cla-backend-legacy`). Port 5000 matches the Cypress functional-test helpers (`tests/functional/utils/run-single-test-local.sh` with `V=1`/`V=2`).
+
+Deployment: the built binary is copied into `cla-backend/bin/` and deployed from the `cla-backend` Serverless stack (`yarn deploy:dev`, `yarn deploy:staging`, or `yarn deploy:prod` from `cla-backend/`).
+
+## AWS Environments & Local Development
+
+Local backend runs point at **real shared AWS environments** (dev/test/staging/prod), not a local stack. The four environments map to AWS accounts via `~/.aws` profiles `lfproduct-dev`, `lfproduct-test`, `lfproduct-staging`, `lfproduct-prod` (assume-role from `lfproduct` base profile, MFA required). See `aws_env.md` for the profile setup and `dev.md` for the assume-role helper script and required env vars (`AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `PRODUCT_DOMAIN`, `ROOT_DOMAIN`, `STAGE`).
+
+Be careful: scripts in `utils/` and `scripts/` can mutate DynamoDB in whichever environment your profile targets, including prod.
+
+## Conventions
+
+- **License headers are enforced in CI for source files** (`.go`, `.py`, `.sh`, `.yaml`/`.yml`, `.txt` — Markdown docs are not scanned) via `check-headers.sh`, which only checks for the `Copyright The Linux Foundation` line, not the SPDX identifier. New code files need `// SPDX-License-Identifier: MIT`; docs need `SPDX-License-Identifier: CC-BY-4.0` by convention, but the checker does not verify this. Only `cla-backend-go`'s `make lint` invokes `check-headers.sh`; `cla-backend-legacy`'s `make lint` (go fmt + go vet) does not.
+- **DCO required** — every commit needs `Signed-off-by`.
+- Use "Approved List" terminology, not "whitelist" (renamed across code, APIs, and specs as of 8/2025).
+- Bot CLA exemptions: see `BOT_ALLOWLIST.md`. Co-authors support: see `CO_AUTHORS.md`. PR-check author/co-author caching design: see `COMMIT_AUTHORS_CACHING.md`.
+
+## CI
+
+GitHub Actions in `.github/workflows/`: `build-pr.yml` (build/test/lint), `cypress-functional-pr.yml` (functional E2E), CodeQL/security/license scans for the Go backends, and `deploy-dev.yml` / `deploy-prod.yml` for deployment (both build `cla-backend-go` and `cla-backend-legacy`, then deploy through the `cla-backend` stack).

cla-backend-go/emails/docusign_templates.go

@@ -3,6 +3,8 @@
 
 package emails
 
+import "github.com/linuxfoundation/easycla/cla-backend-go/utils"
+
 type DocumentSignedTemplateParams struct {
 	CommonEmailParams
 	CLAGroupTemplateParams
@@ -17,25 +19,35 @@ const (
 	// DocumentSignedTemplate is email template for
 	DocumentSignedICLATemplate = `
 		<p>Hello {{.RecipientName}},</p>
-		<p>This is a notification email from EasyCLA regarding the project {{.Project.ExternalProjectName}}.</p>
+		<p>This is a notification email from EasyCLA regarding the {{if eq .Version "v2"}}CLA Group {{.CLAGroupName}}{{else}}project {{.Project.ExternalProjectName}}{{end}}.</p>
 		<p>The CLA has now been signed. You can download the signed CLA as a PDF <a href="{{.PdfLink}}" target="_blank" alt="ICLA Document Link">here</a>.</p>
 		`
 
 	DocumentSignedCCLATemplate = `
 		<p>Hello {{.RecipientName}},</p>
-		<p>This is a notification email from EasyCLA regarding the project {{.Project.ExternalProjectName}}.</p>
+		<p>This is a notification email from EasyCLA regarding the {{if eq .Version "v2"}}CLA Group {{.CLAGroupName}}{{else}}project {{.Project.ExternalProjectName}}{{end}}.</p>
 		<p>The CLA has now been signed. You can download the signed CLA as a PDF <a href="{{.PdfLink}}" target="_blank" alt="CCLA Document Link">here</a>, or from within the <a href="{{.CorporateConsole}}" target="_blank"> EasyCLA CLA Manager console </a>.</p>
 		`
 )
 
 // RenderDocumentSignedTemplate renders RenderDocumentSignedTemplate
-func RenderDocumentSignedTemplate(svc EmailTemplateService, claGroupModelVersion, projectSFID string, params DocumentSignedTemplateParams) (string, error) {
-	claGroupParams, err := svc.GetCLAGroupTemplateParamsFromProjectSFID(claGroupModelVersion, projectSFID)
+func RenderDocumentSignedTemplate(svc EmailTemplateService, claGroupModelVersion, claGroupID, projectSFID string, params DocumentSignedTemplateParams) (string, error) {
+	var (
+		claGroupParams CLAGroupTemplateParams
+		err            error
+	)
+
+	if claGroupModelVersion == utils.V2 {
+		claGroupParams, err = svc.GetCLAGroupTemplateParamsFromCLAGroup(claGroupID)
+	} else {
+		claGroupParams, err = svc.GetCLAGroupTemplateParamsFromProjectSFID(claGroupModelVersion, projectSFID)
+	}
 	if err != nil {
 		return "", err
 	}
 
 	params.CLAGroupTemplateParams = claGroupParams
+	params.Version = claGroupModelVersion
 	var template string
 	if params.ICLA {
 		template = DocumentSignedICLATemplate

cla-backend-go/emails/docusign_templates_test.go

@@ -0,0 +1,223 @@
+// Copyright The Linux Foundation and each contributor to CommunityBridge.
+// SPDX-License-Identifier: MIT
+
+package emails
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/linuxfoundation/easycla/cla-backend-go/utils"
+)
+
+type documentSignedTemplateServiceStub struct {
+	projectParams  CLAGroupTemplateParams
+	claGroupParams CLAGroupTemplateParams
+	projectErr     error
+	claGroupErr    error
+
+	projectLookupCalls  int
+	claGroupLookupCalls int
+	requestedVersion    string
+	requestedProjectID  string
+	requestedCLAGroupID string
+}
+
+var _ EmailTemplateService = (*documentSignedTemplateServiceStub)(nil)
+
+func (s *documentSignedTemplateServiceStub) PrefillV2CLAProjectParams(_ []string) ([]CLAProjectParams, error) {
+	panic("unexpected PrefillV2CLAProjectParams call")
+}
+
+func (s *documentSignedTemplateServiceStub) GetCLAGroupTemplateParamsFromProjectSFID(claGroupVersion, projectSFID string) (CLAGroupTemplateParams, error) {
+	s.projectLookupCalls++
+	s.requestedVersion = claGroupVersion
+	s.requestedProjectID = projectSFID
+	return s.projectParams, s.projectErr
+}
+
+func (s *documentSignedTemplateServiceStub) GetCLAGroupTemplateParamsFromCLAGroup(claGroupID string) (CLAGroupTemplateParams, error) {
+	s.claGroupLookupCalls++
+	s.requestedCLAGroupID = claGroupID
+	return s.claGroupParams, s.claGroupErr
+}
+
+func TestRenderDocumentSignedTemplateUsesVersionAppropriateLookupAndName(t *testing.T) {
+	const (
+		claGroupID   = "d8cead54-92b7-48c5-a2c8-b1e295e8f7f1"
+		projectSFID  = "a0941000002wBz4AAE"
+		claGroupName = "Cloud Native Computing Foundation (CNCF)"
+		projectName  = "OpenTelemetry"
+		pdfLink      = "https://example.test/signed-cla.pdf"
+		v1Console    = "https://legacy-console.example.test"
+		v2Console    = "https://organization.example.test"
+	)
+
+	projectText := "regarding the project " + projectName + "."
+	claGroupText := "regarding the CLA Group " + claGroupName + "."
+
+	testCases := []struct {
+		name      string
+		version   string
+		projectID string
+		icla      bool
+		want      string
+		doNotWant string
+		console   string
+	}{
+		{
+			name:      "V1 ICLA keeps project lookup and project name",
+			version:   utils.V1,
+			projectID: projectSFID,
+			icla:      true,
+			want:      projectText,
+			doNotWant: claGroupText,
+		},
+		{
+			name:      "V1 CCLA keeps project lookup and project name",
+			version:   utils.V1,
+			projectID: projectSFID,
+			want:      projectText,
+			doNotWant: claGroupText,
+			console:   v1Console,
+		},
+		{
+			name:      "V2 ICLA uses exact CLA Group and ignores project mapping",
+			version:   utils.V2,
+			projectID: "malformed-project-sfid-is-ignored-for-v2",
+			icla:      true,
+			want:      claGroupText,
+			doNotWant: projectText,
+		},
+		{
+			name:      "V2 CCLA uses exact CLA Group and ignores project mapping",
+			version:   utils.V2,
+			projectID: "malformed-project-sfid-is-ignored-for-v2",
+			want:      claGroupText,
+			doNotWant: projectText,
+			console:   v2Console,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			svc := &documentSignedTemplateServiceStub{
+				projectParams: CLAGroupTemplateParams{
+					CLAGroupName:     claGroupName,
+					CorporateConsole: v1Console,
+					Version:          utils.V2, // deliberately wrong; the renderer argument is authoritative
+					Projects: []CLAProjectParams{
+						{ExternalProjectName: projectName},
+					},
+				},
+				claGroupParams: CLAGroupTemplateParams{
+					CLAGroupName:     claGroupName,
+					CorporateConsole: v2Console,
+					Version:          utils.V1, // deliberately wrong; the renderer argument is authoritative
+					// No Projects are supplied. V2 rendering must not evaluate Project().
+				},
+			}
+
+			result, err := RenderDocumentSignedTemplate(
+				svc,
+				tc.version,
+				claGroupID,
+				tc.projectID,
+				DocumentSignedTemplateParams{
+					CommonEmailParams: CommonEmailParams{RecipientName: "Heather"},
+					ICLA:              tc.icla,
+					PdfLink:           pdfLink,
+				},
+			)
+			if err != nil {
+				t.Fatalf("RenderDocumentSignedTemplate() error = %v", err)
+			}
+
+			for _, expected := range []string{"Hello Heather", tc.want, pdfLink} {
+				if !strings.Contains(result, expected) {
+					t.Errorf("rendered email does not contain %q: %s", expected, result)
+				}
+			}
+			if strings.Contains(result, tc.doNotWant) {
+				t.Errorf("rendered email unexpectedly contains %q: %s", tc.doNotWant, result)
+			}
+			if tc.console != "" && !strings.Contains(result, tc.console) {
+				t.Errorf("rendered email does not contain corporate console %q: %s", tc.console, result)
+			}
+
+			if tc.version == utils.V2 {
+				if svc.projectLookupCalls != 0 {
+					t.Errorf("project lookup calls = %d, want 0", svc.projectLookupCalls)
+				}
+				if svc.claGroupLookupCalls != 1 {
+					t.Errorf("CLA Group lookup calls = %d, want 1", svc.claGroupLookupCalls)
+				}
+				if svc.requestedCLAGroupID != claGroupID {
+					t.Errorf("requested CLA Group ID = %q, want %q", svc.requestedCLAGroupID, claGroupID)
+				}
+			} else {
+				if svc.projectLookupCalls != 1 {
+					t.Errorf("project lookup calls = %d, want 1", svc.projectLookupCalls)
+				}
+				if svc.claGroupLookupCalls != 0 {
+					t.Errorf("CLA Group lookup calls = %d, want 0", svc.claGroupLookupCalls)
+				}
+				if svc.requestedVersion != tc.version {
+					t.Errorf("requested version = %q, want %q", svc.requestedVersion, tc.version)
+				}
+				if svc.requestedProjectID != tc.projectID {
+					t.Errorf("requested project SFID = %q, want %q", svc.requestedProjectID, tc.projectID)
+				}
+			}
+		})
+	}
+}
+
+func TestRenderDocumentSignedTemplatePropagatesLookupError(t *testing.T) {
+	projectLookupErr := errors.New("project lookup failed")
+	claGroupLookupErr := errors.New("CLA Group lookup failed")
+
+	testCases := []struct {
+		name    string
+		version string
+		svc     *documentSignedTemplateServiceStub
+		wantErr error
+	}{
+		{
+			name:    "V1 project lookup error",
+			version: utils.V1,
+			svc:     &documentSignedTemplateServiceStub{projectErr: projectLookupErr},
+			wantErr: projectLookupErr,
+		},
+		{
+			name:    "V2 exact CLA Group lookup error",
+			version: utils.V2,
+			svc:     &documentSignedTemplateServiceStub{claGroupErr: claGroupLookupErr},
+			wantErr: claGroupLookupErr,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := RenderDocumentSignedTemplate(
+				tc.svc,
+				tc.version,
+				"cla-group-id",
+				"project-sfid",
+				DocumentSignedTemplateParams{},
+			)
+			if !errors.Is(err, tc.wantErr) {
+				t.Fatalf("RenderDocumentSignedTemplate() error = %v, want %v", err, tc.wantErr)
+			}
+
+			if tc.version == utils.V2 {
+				if tc.svc.projectLookupCalls != 0 || tc.svc.claGroupLookupCalls != 1 {
+					t.Errorf("lookup calls: project=%d CLAGroup=%d, want project=0 CLAGroup=1", tc.svc.projectLookupCalls, tc.svc.claGroupLookupCalls)
+				}
+			} else if tc.svc.projectLookupCalls != 1 || tc.svc.claGroupLookupCalls != 0 {
+				t.Errorf("lookup calls: project=%d CLAGroup=%d, want project=1 CLAGroup=0", tc.svc.projectLookupCalls, tc.svc.claGroupLookupCalls)
+			}
+		})
+	}
+}