// Copyright 2025 BioID GmbH.
// Definition of the BioID Web Service (BWS) 3 API.

syntax = "proto3";

package bioid.services.v1;

option java_package = "com.bioid.services";
option csharp_namespace = "BioID.Services";

import "bwsmessages.proto";

// BioID Web Service definition.
service BioIDWebService {
    // Liveness-detection API
    // - 1 image: passive liveness detection only
    // - 2 images: passive and active liveness detection
    // - 2 images and tags: active liveness detection with challenge response
    rpc LivenessDetection (LivenessDetectionRequest) returns (LivenessDetectionResponse);
    // Video liveness-detection API
    rpc VideoLivenessDetection (VideoLivenessDetectionRequest) returns (LivenessDetectionResponse);
    // Photo-verification API
    rpc PhotoVerify (PhotoVerifyRequest) returns (PhotoVerifyResponse);
}

// Liveness detection input images.
message LivenessDetectionRequest {
    // The input image samples.
    repeated ImageData live_images = 1;
}

// Video liveness detection input video.
message VideoLivenessDetectionRequest {
    // The input video.
    bytes video = 1;
}

// Liveness detection output.
message LivenessDetectionResponse {
    // The return-status of the processing job.
    JobStatus status = 1;
    // Any error messages collected during processing.
    repeated JobError errors = 2;
    // Calculated image properties for each of the provided images in the given order.
    repeated ImageProperties image_properties = 3;
    // The liveness decision.
    bool live = 4;
    // The calculated liveness score that led to the live decision.
    double liveness_score = 5;
}

// Photo-verification input images and flags.
message PhotoVerifyRequest {
    // One or more live images.
    repeated ImageData live_images = 1;
    // The ID-photo image.
    bytes photo = 2;
    // Flag to switch off LivenessDetection which is enabled by default.
    bool disable_liveness_detection = 3;
}

// Photo-verification output.
message PhotoVerifyResponse {
    // The return-status of the processing job.
    JobStatus status = 1;
    // Any error messages collected during processing.
    repeated JobError errors = 2;
    // Calculated image properties for each of the provided live images if available.
    repeated ImageProperties image_properties = 3;
    // Calculated image properties for the provided photo.
    ImageProperties photo_properties = 4;
    // The determined verification level.
    AccuracyLevel verification_level = 5;
    // The calculated verification score that led to the decision for the verification level.
    double verification_score = 6;
    // In case a liveness detection was performed, here is the liveness decision.
    bool live = 7;
    // The calculated liveness score that led to the live decision.
    double liveness_score = 8;

    // Verification accuracy levels.
    // We recommend not to accept verified persons with low verification levels.
    enum AccuracyLevel {
        // The person has not be recognized at all.
        NOT_RECOGNIZED = 0;
        // Worst accuracy level that correlates with a FAR of 0.5%
        LEVEL_1 = 1;
        // Bad accuracy level that correlates with a FAR of 0.25%
        LEVEL_2 = 2;
        // Not so good accuracy level that correlates with a FAR of 0.1%
        LEVEL_3 = 3;
        // Good accuracy level that correlates with a FAR of 0.01%
        LEVEL_4 = 4;
        // Best accuracy level that correlates with a FAR of 0.001%
        LEVEL_5 = 5;
    }
}