Add PhoneLookupMode config and phone-lookup annotations (#509)

* Add PhoneLookupMode config and phone-lookup annotations

- Add PhoneLookupMode (disabled/log/enabled) to RegistrationServiceVerificationConfig
- Add phone-lookup annotation key constants to UserSignup
- Regenerate deepcopy, openapi, CRD docs

Signed-off-by: Feny Mehta <fbm3307@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: fbm3307

api/v1alpha1/docs/apiref.adoc

@@ -1873,6 +1873,23 @@ The value replaces all occurrences of the Parameter {{.NAME}}. + |  |
 |===
 
 
+[id="{anchor_prefix}-github-com-codeready-toolchain-api-api-v1alpha1-phonelookupmode"]
+==== PhoneLookupMode
+
+_Underlying type:_ _string_
+
+PhoneLookupMode defines the mode for Twilio Lookup v2 phone risk checks
+
+.Validation:
+- Enum: [disabled log enabled]
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-codeready-toolchain-api-api-v1alpha1-registrationserviceverificationconfig[$$RegistrationServiceVerificationConfig$$]
+****
+
+
+
 
 
 [id="{anchor_prefix}-github-com-codeready-toolchain-api-api-v1alpha1-propagatedclaims"]
@@ -2280,6 +2297,14 @@ See https://docs.aws.amazon.com/sns/latest/dg/sms_publish-to-phone.html for deta
 
 | *`twilioSenderConfigs`* __xref:{anchor_prefix}-github-com-codeready-toolchain-api-api-v1alpha1-twiliosenderconfig[$$TwilioSenderConfig$$] array__ | TwilioSenderConfigs is an array of TwilioSenderConfig objects + |  | Optional: \{} +
 
+| *`phoneLookupMode`* __xref:{anchor_prefix}-github-com-codeready-toolchain-api-api-v1alpha1-phonelookupmode[$$PhoneLookupMode$$]__ | PhoneLookupMode controls how the registration service handles Twilio Lookup v2 phone risk checks. +
+Valid values are "disabled" (skip Lookup entirely), "log" (call Lookup and store results but don't block), +
+and "enabled" (call Lookup and enforce blocking). Defaults to "log". + | log | Enum: [disabled log enabled] +
+Optional: \{} +
+
+| *`phoneLookupExcludedCountries`* __string array__ | PhoneLookupExcludedCountries is a list of ISO 3166-1 alpha-2 country codes (e.g. ["CA", "US"]) +
+for which Twilio Lookup should be skipped. + |  | Optional: \{} +
+
 |===
 
 

api/v1alpha1/toolchainconfig_types.go

@@ -316,6 +316,16 @@ type RegistrationServiceAuthConfig struct {
 	SSORealm *string `json:"ssoRealm,omitempty"`
 }
 
+// PhoneLookupMode defines the mode for Twilio Lookup v2 phone risk checks
+// +kubebuilder:validation:Enum=disabled;log;enabled
+type PhoneLookupMode string
+
+const (
+	PhoneLookupModeDisabled PhoneLookupMode = "disabled"
+	PhoneLookupModeLog      PhoneLookupMode = "log"
+	PhoneLookupModeEnabled  PhoneLookupMode = "enabled"
+)
+
 // RegistrationServiceVerificationConfig contains the subset of registration service configuration parameters related to verification
 // +k8s:openapi-gen=true
 type RegistrationServiceVerificationConfig struct {
@@ -386,6 +396,19 @@ type RegistrationServiceVerificationConfig struct {
 	// +optional
 	// +listType=atomic
 	TwilioSenderConfigs []TwilioSenderConfig `json:"twilioSenderConfigs,omitempty"`
+
+	// PhoneLookupMode controls how the registration service handles Twilio Lookup v2 phone risk checks.
+	// Valid values are "disabled" (skip Lookup entirely), "log" (call Lookup and store results but don't block),
+	// and "enabled" (call Lookup and enforce blocking). Defaults to "log".
+	// +optional
+	// +kubebuilder:default="log"
+	PhoneLookupMode *PhoneLookupMode `json:"phoneLookupMode,omitempty"`
+
+	// PhoneLookupExcludedCountries is a list of ISO 3166-1 alpha-2 country codes (e.g. ["CA", "US"])
+	// for which Twilio Lookup should be skipped.
+	// +optional
+	// +listType=set
+	PhoneLookupExcludedCountries []string `json:"phoneLookupExcludedCountries,omitempty"`
 }
 
 // TwilioSenderConfig is used to associate a particular sender ID (a sender ID is a text value that appears instead of

api/v1alpha1/usersignup_types.go

@@ -52,6 +52,13 @@ const (
 	// The time is stored in time.RFC3339 format, the reason is that the main purpose of the metric is to track the UX of the users, and milliseconds don't really matter in that case
 	UserSignupRequestReceivedTimeAnnotationKey = LabelKeyPrefix + "request-received-time"
 
+	// UserSignupPhoneLookupCarrierRiskAnnotationKey stores the carrier_risk_category from Twilio Lookup (e.g. "low", "moderate", "high")
+	UserSignupPhoneLookupCarrierRiskAnnotationKey = LabelKeyPrefix + "phone-lookup-carrier-risk"
+	// UserSignupPhoneLookupNumberBlockedAnnotationKey stores whether the number is blocked ("true"/"false")
+	UserSignupPhoneLookupNumberBlockedAnnotationKey = LabelKeyPrefix + "phone-lookup-number-blocked"
+	// UserSignupPhoneLookupDetailsAnnotationKey stores a single-line JSON value with supplementary lookup data
+	UserSignupPhoneLookupDetailsAnnotationKey = LabelKeyPrefix + "phone-lookup-details"
+
 	// UserSignupUserEmailHashLabelKey is used for the usersignup email hash label key
 	UserSignupUserEmailHashLabelKey = LabelKeyPrefix + "email-hash"
 	// UserSignupUserPhoneHashLabelKey is used for the usersignup phone hash label key