feat: add AddIpOverride RPC

Google APIs · copybara-github · commit cc4e33a26333 · 2024-08-20T10:00:16.000-07:00
feat: add `express_settings` to `Key`
docs: clarify `Event.express` field
docs: fix billing, quota, and usecase links

PiperOrigin-RevId: 665409132
diff --git a/google/cloud/recaptchaenterprise/v1/recaptchaenterprise.proto b/google/cloud/recaptchaenterprise/v1/recaptchaenterprise.proto
@@ -127,6 +127,18 @@ service RecaptchaEnterpriseService {
     };
   }
 
+  // Adds an IP override to a key. The following restrictions hold:
+  // * The maximum number of IP overrides per key is 100.
+  // * For any conflict (such as IP already exists or IP part of an existing
+  //   IP range), an error will be returned.
+  rpc AddIpOverride(AddIpOverrideRequest) returns (AddIpOverrideResponse) {
+    option (google.api.http) = {
+      post: "/v1/{name=projects/*/keys/*}:addIpOverride"
+      body: "*"
+    };
+    option (google.api.method_signature) = "name,ip_override_data";
+  }
+
   // Get some aggregated metrics for a Key. This data can be used to build
   // dashboards.
   rpc GetMetrics(GetMetricsRequest) returns (Metrics) {
@@ -708,8 +720,7 @@ message Event {
       [deprecated = true, (google.api.field_behavior) = OPTIONAL];
 
   // Optional. Flag for a reCAPTCHA express request for an assessment without a
-  // token. If enabled, `site_key` must reference a SCORE key with WAF feature
-  // set to EXPRESS.
+  // token. If enabled, `site_key` must reference an Express site key.
   bool express = 14 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. The URI resource the user requested that triggered an assessment.
@@ -1388,11 +1399,11 @@ message MigrateKeyRequest {
   // Optional. If true, skips the billing check.
   // A reCAPTCHA Enterprise key or migrated key behaves differently than a
   // reCAPTCHA (non-Enterprise version) key when you reach a quota limit (see
-  // https://cloud.google.com/recaptcha-enterprise/quotas#quota_limit). To avoid
+  // https://cloud.google.com/recaptcha/quotas#quota_limit). To avoid
   // any disruption of your usage, we check that a billing account is present.
   // If your usage of reCAPTCHA is under the free quota, you can safely skip the
   // billing check and proceed with the migration. See
-  // https://cloud.google.com/recaptcha-enterprise/docs/billing-information.
+  // https://cloud.google.com/recaptcha/docs/billing-information.
   bool skip_billing_check = 2 [(google.api.field_behavior) = OPTIONAL];
 }
 
@@ -1475,10 +1486,13 @@ message Key {
 
     // Settings for keys that can be used by iOS apps.
     IOSKeySettings ios_settings = 5;
+
+    // Settings for keys that can be used by reCAPTCHA Express.
+    ExpressKeySettings express_settings = 11;
   }
 
   // Optional. See [Creating and managing labels]
-  // (https://cloud.google.com/recaptcha-enterprise/docs/labels).
+  // (https://cloud.google.com/recaptcha/docs/labels).
   map<string, string> labels = 6 [(google.api.field_behavior) = OPTIONAL];
 
   // Output only. The timestamp corresponding to the creation of this key.
@@ -1618,6 +1632,9 @@ message IOSKeySettings {
       [(google.api.field_behavior) = OPTIONAL];
 }
 
+// Settings specific to keys that can be used for reCAPTCHA Express.
+message ExpressKeySettings {}
+
 // Contains fields that are required to perform Apple-specific integrity checks.
 message AppleDeveloperId {
   // Required. Input only. A private key (downloaded as a text file with a .p8
@@ -1919,6 +1936,24 @@ message SearchRelatedAccountGroupMembershipsResponse {
   string next_page_token = 2;
 }
 
+// The AddIpOverride request message.
+message AddIpOverrideRequest {
+  // Required. The name of the key to which the IP override is added, in the
+  // format `projects/{project}/keys/{key}`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "recaptchaenterprise.googleapis.com/Key"
+    }
+  ];
+
+  // Required. IP override added to the key.
+  IpOverrideData ip_override_data = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Response for AddIpOverride.
+message AddIpOverrideResponse {}
+
 // A membership in a group of related accounts.
 message RelatedAccountGroupMembership {
   option (google.api.resource) = {
@@ -1969,7 +2004,7 @@ message RelatedAccountGroup {
 // Firewall).
 message WafSettings {
   // Supported WAF features. For more information, see
-  // https://cloud.google.com/recaptcha-enterprise/docs/usecase#comparison_of_features.
+  // https://cloud.google.com/recaptcha/docs/usecase#comparison_of_features.
   enum WafFeature {
     // Undefined feature.
     WAF_FEATURE_UNSPECIFIED = 0;
@@ -2010,3 +2045,31 @@ message WafSettings {
   // Required. The WAF feature for which this key is enabled.
   WafFeature waf_feature = 2 [(google.api.field_behavior) = REQUIRED];
 }
+
+// Information about the IP or IP range override.
+message IpOverrideData {
+  // Enum that represents the type of IP override.
+  enum OverrideType {
+    // Default override type that indicates this enum hasn't been specified.
+    OVERRIDE_TYPE_UNSPECIFIED = 0;
+
+    // Allowlist the IP address; i.e. give a `risk_analysis.score` of 0.9 for
+    // all valid assessments.
+    ALLOW = 1;
+  }
+
+  // Required. The IP address to override (can be IPv4, IPv6 or CIDR).
+  // The IP override must be a valid IPv4 or IPv6 address, or a CIDR range.
+  // The IP override must be a public IP address.
+  // Example of IPv4: 168.192.5.6
+  // Example of IPv6: 2001:0000:130F:0000:0000:09C0:876A:130B
+  // Example of IPv4 with CIDR: 168.192.5.0/24
+  // Example of IPv6 with CIDR: 2001:0DB8:1234::/48
+  string ip = 1 [
+    (google.api.field_info).format = IPV4_OR_IPV6,
+    (google.api.field_behavior) = REQUIRED
+  ];
+
+  // Required. Describes the type of IP override.
+  OverrideType override_type = 3 [(google.api.field_behavior) = REQUIRED];
+}
