Skip to content

Service architecture#

The Service architecture is shown in the diagram (Figure 1), a description of the architecture components is presented below (Table 1).

General scheme of LUNA PASS architecture
Figure 1. General scheme of LUNA PASS architecture

Table 1. Components of the LUNA PASS architecture

Component name

Description of interaction

LUNA PASS UI

LUNA PASS client component responsible for capturing video stream, sending video stream frames to LUNA PASS API and displaying processing results.

An external system with similar functions can be used instead of LUNA PASS UI, provided that the LPProto protocol is used to connect to the Backend (see the "LPProto protocol" section for operating principle).

LUNA PASS API

LUNA PASS server component, built on AIOHTTP. It processes frame, checks image and Liveness using plugins, then, based on the results of the check, makes decisions about whether the image passes inspection.

LUNA Configurator

LP5 component that stores configurations of all services.

LUNA Licenses

LUNA Licenses contains information about available licensed features and their limitations, provides information about license conditions to LUNA PASS components: license expiration date; maximum number of created faces with descriptors; information about the availability of Liveness and Deepfake.

LUNA Licenses is required for the operation of the Service components and their interaction with the LP5 components.

LUNA Remote SDK

VisionLabs development kit including libraries and neural networks for detection, attribute estimation and Liveness estimation on the acquired face image.

LUNA PASS VIDEO

LUNA PASS server component that implements the gluing of frames received within LUNA PASS API sessions into video.

NGINX

Optional component. HTTP server and reverse proxy server for load balancing.

It is not part of the product, install and configure component separately (see the "Appendix" secion).

LPProto

A transport layer information transfer protocol that defines the structure of transmitted frames using WebSocket.

Frame is a fragment of protocol data. See LPProto Protocol section for the list of frames.

The first frame is processed in five stages (Table 2).

Table 2. Frame processing stages

Stage

Description

1

PreProcessing—preliminary frame processing (implementation of the LPProto protocol, conversion, etc.), as well as the operation of plugins that do not need frames

2

Frame processing using Remote SDK (2-3) 1. Evaluation and selection of the "main" face; 2. Evaluation of the biometric sample; 3. Evaluation of face/head attributes; 4. Checking whether the session was previously marked as fake; 5. Liveness evaluation, Deepfake and descriptor extraction.

In case of errors, frame processing is terminated.

3

Parallel operation of FaceMatcher, ActiveLiveness, VirtualCameraChecker plugins.

4

Decision Phase—the stage of making a decision on further continuation of the session, if, for example:

  • the frame limit has been exhausted;
  • bestshot received, etc.

5

Response to the caller and creation of background tasks for file post-processing (FileLogger, VideoRedis, etc.), which must complete either before the end of the session or before receiving the next frame.

LUNA PASS API forms a JWT packet with the bestshot, on successful passing of Liveness. The network communication scheme is shown below (Figure 2).

Scheme of network interaction of LUNA PASS components
Figure 2. Scheme of network interaction of LUNA PASS components

LPProto Protocol#

LPProto is a transport layer protocol developed by VisionLabs to restrict information transmitted using WebSocket. The principle of operation is transmission of consecutive frames with messages.

Frame is a fragment of protocol data, which must be specified strictly according to the template. The definition applies only to this section, in the rest of the document the frame is a part of the video stream. The first line of each frame specifies its command within the protocol.

Connection settings that are transmitted as part of the CONNECT command:

  • heartbeat:1000
  • session-id:623e1bbc-24f9-4d84-907f-8000978ec2a1

The session ID is passed in the session-id header when the connection is initialized.

LPProto protocol format#

A schematic representation of the protocol format is shown below (Figure 3).

Protocol format
Figure 3. Protocol format

The message consists of three lines:

  • First line – message type or command (Table 3);
  • The second line – section with any number of headers;
  • The third line – message body, separated by an empty line.

Table 3. Supported message types

Command

Description

Example

CONNECT

Start request to establish a connection to the LUNA PASS API.

Without an established connection, work is not possible.

Acceptable headings:

  • version – LPProto protocol version.

  • heartbeat – optional activation of background requests every N ms to keep WebSocket open (see the HEARTBEAT command).

Possible answers:

  • CONNECTED – successful connection;

  • ERROR – connection error.

CONNECT

version:1.0

heartbeat:1000

CONNECTED

Response from LUNA PASS API about successful connection to LUNA PASS UI over WebSocket.

Acceptable headings:

  • session-id – Session UUID, the unique value of the connection;

  • version – LPProto protocol version.

CONNECTED

session-id:623e1bbc-24f9-4d84 -907f-8000978ec2a1

version: 1.0

FRAME

A request from LUNA PASS UI containing information about the image: a frame of the video stream in the format specified in the content-type header.

Acceptable headings:

  • content-type – type of transmitted image

  • One line indent

  • Frame body – base64 image.

Possible answers:

STATS – image/face failed the test;

SUCCESS – the test was successful;

ERROR – error within a frame check request.

LUNA PASS UI restriction: the next FRAME cannot be sent until a response is received, this is necessary to synchronize data sending, including cases of using multiple LUNA PASS UI instances and minimize errors.

FRAME

content-type:image/x-jpeg-base64

/9j/4AAQSkZJRgABAQABAA…

STATS

LUNA PASS API response after unsuccessful image estimation, containing the error codes detected (see /docs/jslib/lpErrors.js.html for a list of errors).

If a face was found in the image, the BBox information is returned.

Acceptable headings:

  • content-type—the type of message being transmitted;

  • details—frame estimates, including BBox position The set of estimates depends on server implementation, there are no restrictions within the protocol.

  • errors—error list after image estimation (see /docs/jslib/lpErrors.js.html for error codes).

  • isOk—a boolean value that indicates whether the FRAME request was successfully executed.

STATS

content-type:application/json

{isOk: false, errors: [12], details: {,…}}

details: {,…}

details: {,…}

errors: [12]

isOk: false

SUCCESS

LUNA PASS API response after successfully validating the image, selecting the bestshot and evaluating the face.

Acceptable headings:

  • content-type – the type of message being transmitted;

  • One line indent.

  • Frame body – information about image estimation in JWT format

After receiving the frame WebSocket connection is closed. Further work requires reconnection.

SUCCESS

content-type:application/jwt

eyJ0eXAiOiJKV…

ERROR

LUNA PASS API response when an internal error occurs:

  • Incorrect installation;

  • Communication break;

  • Incorrect license;

  • Other system errors.

Acceptable headings:

  • error – error code.

The following system errors exist in this version:

  • 1002 – internal server error

ERROR

error: 1002

HEARTBEAT

Optional recurring background request from Backend to keep WebSocket open. See CONNECT for how to enable it.

Sends an empty frame every N ms.

HEARTBEAT

JWT package#

JSON Web Token (JWT) – A JSON object that allows signed text information to be transmitted.

JThe WT consists of 3 parts, separated by dots—header.payload.signature. The sections use Base64 encoding:

1․ Title: Header

Description: JWT Type Information.

Example of decoded Base64:

The following attributes are used during LUNA PASS operation: { "alg": "HS256", "typ": "JWT" }. The "algorithm" attribute is configured in lunapassapi in JWT configuration parameters.

2․ Title: Payload

Description: A message body containing information on the recognized attributes.

See /docs/jslib/LunaPass.js.html for a detailed description.

Example decoded Base64: 

{
    "errors": [],
    "bestshot": "***",
    "estimations": {
    "faceCount": 1,
    "ags": null,
    "imageQuality": {
      "blur": 0.9192548394203186,
      "isBlurred": false,
      "light": 0.7044228315353394,
      "isHighlighted": false,
      "darkness": 0.7675179243087769,
      "isDark": false,
      "illumination": 0.2165278196334839,
      "isIlluminated": false,
      "specularity": 0.5341013669967651,
      "isSpecular": false
    },
    "faceFramePosition": {
      "faceRect": {
        "x": 135,
        "y": 167,
        "width": 243,
        "height": 336
      },
      "frameRect": {
        "x": 0,
        "y": 0,
        "width": 480,
        "height": 640
      },
      "margins": [
        167,
        102,
        137,
        135
      ]
    },
    "headPose": {
      "yaw": 6.0508646965026855,
      "roll": 0.8311771750450134,
      "pitch": 3.0268990993499756
    },
    "eyes": {
      "left": "open",
      "right": "open",
      "state": "open"
    },
    "mouth": {
      "opened": 0.013608532957732677,
      "smile": 0.0012621879577636719,
      "occluded": 0.0009340881952084601,
      "state": "opened"
    },
    "eyeglasses": "no_glasses",
    "deepfake": {
      "score": 0.9797163605690002,
      "state": "real"
    },
    "liveness": {
      "score": 0.9812202453613281
    }
  },
  "isOk": true,
  "iat": 1747917134,
  "jti": "d52158fa-e154-4203-9bc0-b6045b7a1a1f"
}

3․ Title: Signature

Description: Unique message signature.