Implement SSS HTTP client with Auth0 M2M authentication

[mlehotskylf]

Parent: #4985
Depends on: #4986 (Auth0 grant)

Context

Create a Go HTTP client package that EasyCLA uses to call the Sanctions Screening Service. This is a building block — the integration into the CCLA/ECLA flows is a separate ticket.

What to build

A Go package (e.g., sss/client.go) that:

1. Acquires and caches Auth0 M2M tokens

Call POST https://{auth0_domain}/oauth/token with client_credentials grant. Cache the token in memory (tokens are valid 24h). Refresh 1 minute before expiry.

2. Calls SSS

GET /api/v1/organizations/status with query parameters and Bearer token.

3. Returns a typed response

type ScreeningResult struct {
    Status     string    // "clean" or "flagged"
    EntityID   string    // SSS entity UUID
    Source     string    // "screening_db", "sfdc", or "descartes_api"
    ScreenedAt time.Time
}

4. Handles errors

• 400 → caller error (bad params) → return error with details
• 401/403 → auth error → return error, log for investigation
• 503 + Retry-After header → SSS vendor unavailable → return specific error type so caller can decide policy
• Timeout (10s suggested) → return specific error type

Configuration

type SSSConfig struct {
    BaseURL           string // per-environment SSS URL
    Auth0Domain       string // per-environment Auth0 domain
    Auth0ClientID     string
    Auth0ClientSecret string
    Auth0Audience     string // per-environment SSS audience
    Timeout           time.Duration
}

Environment values

Env	BaseURL	Auth0Domain	Auth0Audience
Dev	https://sanctions-screening.dev.v2.cluster.linuxfound.info	linuxfoundation-dev.auth0.com	https://sanctions-screening.dev.v2.cluster.linuxfound.info/
Staging	https://sanctions-screening.staging.v2.cluster.linuxfound.info	linuxfoundation-staging.auth0.com	https://sanctions-screening.staging.v2.cluster.linuxfound.info/
Prod	https://sanctions-screening.lfx.linuxfoundation.org	linuxfoundation.auth0.com	https://sanctions-screening.lfx.linuxfoundation.org/

Unit tests

• Mock HTTP responses for clean, flagged, 400, 401, 503
• Token caching: verify second call reuses cached token
• Token refresh: verify expired token triggers new acquisition

Acceptance criteria

• Client can authenticate and call SSS dev environment
• Token is cached and reused across calls
• Errors return typed error values the caller can match on
• Unit tests pass with mocked HTTP

References

• SSS API spec: docs/api-specification.md
• SSS integration guide: docs/integration-guide.md

[lukaszgryglicki]

cc @psrsingh

[lukaszgryglicki]

This is done via #5058 - already deployed to dev and prod. Keeping this in Ready-for-review as there are no consumers yet so it is not tested.

[psrsingh]

This is done via #5058 - already deployed to dev and prod. Keeping this in Ready-for-review as there are no consumers yet so it is not tested.

okay

[lukaszgryglicki]

This needs validation on dev - ETA: next week.

[psrsingh]

This needs validation on dev - ETA: next week.

can u send me the dev url again ??

[lukaszgryglicki]

Repo where easyCLA (dev) is installed: https://github.com/mlehotskylf-org2/easycla-dev.
Actual API endpoint V1/V2 (legacy): https://api.lfcla.dev.platform.linuxfoundation.org.
Actual API endpoint V3/V4 (current): https://api-gw.dev.platform.linuxfoundation.org/cla-service.