.. Relock Cloud Deployment documentation master file, created by
   sphinx-quickstart on Wed Aug 20 11:05:55 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Simple Integration
==================

We recommend this option for OTP-heavy sign-in flows, particularly when the authentication process relies on SMS codes, which are especially vulnerable to phishing attacks. By introducing Relock at this stage, you add an extra verification layer before the user even enters their credentials. This helps reduce the risk of attackers intercepting SMS-based one-time codes and reduces the costs, ensuring that only trusted devices can complete the authentication process.

Use Case Example
~~~~~~~~~~~~~~~~

For OTP-heavy login flows, you may want Relock verification to trigger when the user clicks "Sign In," *before* password entry. Based on Relock’s response, you could redirect the user either to a password-only flow or to a password + OTP flow.

New Cloud Relock Gateway
~~~~~~~~~~~~~~~~~~~~~~~~

   1. Create an account and sign in at: 
      
      ``https://relock.host``  

   2. Define and add the domain name protected by a new Relock gateway, e.g.:

      ``example.com``

   3. Configure your Relock Cloud subdomain (Wildcard ID):

      ``example.relock.host``  

   4. Configure return routes (URLs) for completed verification:

      Known/**Trusted** → ``https://example.com/password_only``
      
      New/**Fresh** → ``https://example.com/send_sms_otp``  

      (in the Core settings tab)

   5. Get a *public key* for verifying Relock responses (in the *Gateway Access Keys* tab).

.. rst-class:: break_before

Web Application Changes
~~~~~~~~~~~~~~~~~~~~~~~

When a user triggers a sign-in action (clicks the sign-in button), redirect the user to the authentication gateway:

.. code-block:: bash

  https://example.relock.host/<RANDOM_UUID>

The gateway verifies the user’s device identity, confirms and rotates cryptographic keys, and then redirects the browser to one of the pre-configured routes (URLs) to trigger the appropriate action.

The redirect back to your application will be sent as a **POST** request containing a cryptographically signed Random_UUID, along with additional information about the device.

Authentication Flow
~~~~~~~~~~~~~~~~~~~

   1. **Sign-in Triggered**  
      The user is redirected to the third-party cloud authentication gateway hosted at the ``example.relock.host`` domain.

   2. **Spinner / Loading Page**  
      Cryptographic keys are verified and rotated in the background. Based on the result of this verification, a redirect back to the web application is triggered.

   3. **Redirect Back to the Web Application**  

      *Trusted Device* →  
      The user proceeds directly to password entry, accompanied by a one-time token and a cryptographic signature proving the device is trusted.

      *New Device* →  
      A fresh credential is enrolled on the third-party domain. The authentication flow must then continue with an additional factor, such as an OTP code (e.g., password + OTP or email confirmation).

Response Verification
~~~~~~~~~~~~~~~~~~~~~

Always verify Relock’s response signature using Ed25519 with the public key generated in the Admin Panel. This ensures that every response truly originates from Relock and has not been tampered with in transit. The signature validation step protects your application from replay attacks, forged redirects, or malicious third parties attempting to impersonate Relock. The Ed25519 algorithm is designed to provide strong cryptographic guarantees while remaining lightweight and efficient, making it ideal for real-time verification inside your authentication flow.

.. rst-class:: break_before

Verifying gateway signature
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The snippet below shows a minimal, end-to-end verification of an authentication gateway response using an **Ed25519** public key. 

In this example:

   ``X-Key-Transaction`` is the exact byte string that was signed (a UUID originally provided to the authentication gateway by the web application server).

   ``X-Key-Transaction-Signature`` is the **hex-encoded** Ed25519 signature of that UUID, after it has been encoded into its raw byte representation.

.. code-block:: python

   import base64
   import binascii
   from nacl.signing import VerifyKey

   transaction = request.form.get('X-Key-Transaction', str())
   signature_hex = request.form.get('X-Key-Transaction-Signature', str())

   # GET a public key from Relock Admin panel
   public_key_b64 = "9BvLN49xYMLfUnVLi4ncvdIQHrhEo6/A15EaPHas2B4="

   transaction = binascii.unhexlify(transaction)
   signature = binascii.unhexlify(signature_hex)
   public_key = base64.b64decode(public_key_b64)
   # Verify signature
   verify_key = VerifyKey(public_key)
   try:
       verify_key.verify(transaction.encode(), signature)
   except Exception as e:
       print("Signature invalid:", e)

Notes and Best Practices
~~~~~~~~~~~~~~~~~~~~~~~~

   **Verify the exact bytes**: The signed content must match byte-for-byte. If Relock signs a canonical payload (e.g., UTF-8 JSON or a UUID string), verify *that exact representation* (same encoding, no whitespace changes).

   **Verify Key sizes**: Ed25519 uses a 32-byte public key and 64-byte signature. Reject keys/signatures with unexpected lengths.