kratos/third_party/google/cloud/recaptchaenterprise/v1beta1/recaptchaenterprise.proto

// Copyright 2019 Google LLC.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

syntax = "proto3";

package google.cloud.recaptchaenterprise.v1beta1;

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.RecaptchaEnterprise.V1Beta1";
option go_package = "google.golang.org/genproto/googleapis/cloud/recaptchaenterprise/v1beta1;recaptchaenterprise";
option java_multiple_files = true;
option java_outer_classname = "RecaptchaEnterpriseProto";
option java_package = "com.google.recaptchaenterprise.v1beta1";
option objc_class_prefix = "GCRE";
option php_namespace = "Google\\Cloud\\RecaptchaEnterprise\\V1beta1";


// Service to determine the likelihood an event is legitimate.
service RecaptchaEnterpriseServiceV1Beta1 {
  // Creates an Assessment of the likelihood an event is legitimate.
  rpc CreateAssessment(CreateAssessmentRequest) returns (Assessment) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*}/assessments"
      body: "assessment"
    };
  }

  // Annotates a previously created Assessment to provide additional information
  // on whether the event turned out to be authentic or fradulent.
  rpc AnnotateAssessment(AnnotateAssessmentRequest) returns (AnnotateAssessmentResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{name=projects/*/assessments/*}:annotate"
      body: "*"
    };
  }
}

// The create assessment request message.
message CreateAssessmentRequest {
  // Required. The name of the project in which the assessment will be created,
  // in the format "projects/{project_number}".
  string parent = 1;

  // The asessment details.
  Assessment assessment = 2;
}

// The request message to annotate an Assessment.
message AnnotateAssessmentRequest {
  // Enum that reprensents the types of annotations.
  enum Annotation {
    // Default unspecified type.
    ANNOTATION_UNSPECIFIED = 0;

    // Provides information that the event turned out to be legitimate.
    LEGITIMATE = 1;

    // Provides information that the event turned out to be fraudulent.
    FRAUDULENT = 2;
  }

  // Required. The resource name of the Assessment, in the format
  // "projects/{project_number}/assessments/{assessment_id}".
  string name = 1;

  // The annotation that will be assigned to the Event.
  Annotation annotation = 2;
}

// Empty response for AnnotateAssessment.
message AnnotateAssessmentResponse {

}

// A recaptcha assessment resource.
message Assessment {
  // LINT.IfChange(classification_reason)
  // Reasons contributing to the risk analysis verdict.
  enum ClassificationReason {
    // Default unspecified type.
    CLASSIFICATION_REASON_UNSPECIFIED = 0;

    // The event appeared to be automated.
    AUTOMATION = 1;

    // The event was not made from the proper context on the real site.
    UNEXPECTED_ENVIRONMENT = 2;

    // Browsing behavior leading up to the event was generated was out of the
    // ordinary.
    UNEXPECTED_USAGE_PATTERNS = 4;

    // Too little traffic has been received from this site thus far to generate
    // quality risk analysis.
    PROVISIONAL_RISK_ANALYSIS = 5;
  }

  // Output only. The resource name for the Assessment in the format
  // "projects/{project_number}/assessments/{assessment_id}".
  string name = 1;

  // The event being assessed.
  Event event = 2;

  // Output only. Legitimate event score from 0.0 to 1.0.
  // (1.0 means very likely legitimate traffic while 0.0 means very likely
  // non-legitimate traffic).
  float score = 3;

  // Output only. Properties of the provided event token.
  TokenProperties token_properties = 4;

  // Output only. Reasons contributing to the risk analysis verdict.
  repeated ClassificationReason reasons = 5;
}

message Event {
  // The user response token provided by the reCAPTCHA client-side integration
  // on your site.
  string token = 1;

  // The site key that was used to invoke reCAPTCHA on your site and generate
  // the token.
  string site_key = 2;
}

message TokenProperties {
  // Enum that represents the types of invalid token reasons.
  enum InvalidReason {
    // Default unspecified type.
    INVALID_REASON_UNSPECIFIED = 0;

    // If the failure reason was not accounted for.
    UNKNOWN_INVALID_REASON = 1;

    // The provided user verification token was malformed.
    MALFORMED = 2;

    // The user verification token had expired.
    EXPIRED = 3;

    // The user verification had already been seen.
    DUPE = 4;

    // The user verification token did not match the provided site secret.
    // This may be a configuration error (e.g. development keys used in
    // production) or end users trying to use verification tokens from other
    // sites.
    SITE_MISMATCH = 5;

    // The user verification token was not present.  It is a required input.
    MISSING = 6;
  }

  // Output only. Whether the provided user response token is valid.
  bool valid = 1;

  // Output only. Reason associated with the response when valid = false.
  InvalidReason invalid_reason = 2;

  // Output only. The timestamp corresponding to the generation of the token.
  google.protobuf.Timestamp create_time = 3;

  // Output only. The hostname of the page on which the token was generated.
  string hostname = 4;

  // Output only. Action name provided at token generation.
  string action = 5;
}