Technical & Security Architecture

1. Client-Side Seed Generation

The creation of the user's wallet is processed entirely on the client side using the browser's cryptographic sandbox. SatoLink does not generate, witness, or store seed phrases.

2. Local Cryptographic Vault (Cifrado & Storage)

Once the 12-word mnemonic is generated or imported, it is protected with symmetric authenticated encryption before being saved on physical storage.

{
  "link": "username",
  "walletData": {
    "encryptedMnemonic": "Base64(Ciphertext)",
    "salt": "Base64(Salt)",
    "iv": "Base64(IV)"
  }
}

3. Breez Liquid SDK Node Instance

SatoLink compiles Rust-native nodes into **WebAssembly (WASM)** modules via @breeztech/breez-sdk-liquid, permitting the browser to act as a light node on the Liquid sidechain.

4. Submarine Swaps & LNURL-pay (Trustless Routing)

Since the user's keys are only on their client device, they cannot sign transactions when offline. SatoLink overcomes this limitation through **Submarine Swaps** (atomic swaps) coordinated over LNURL-pay.

When a payer resolves user@satolink.com:

1. The server queries the DB for the next unused Liquid address in the recipient's pre-generated pool.
2. The server requests a Submarine Swap from the liquidity provider (Boltz). The swap links the recipient's Liquid address to a Lightning Invoice.
3. The server serves the Bolt11 invoice to the payer. Once paid, the swap provider automatically locks the funds into a Hash Time-Locked Contract (HTLC) on-chain on the Liquid sidechain.
4. When the receiver opens their wallet client, the Breez SDK scans the Liquid blockchain, discovers the pending HTLC, reveals the local preimage, and claims the Liquid BTC/USDT directly to their local custody.

5. Challenge-Response API Specification

The authentication API endpoints expect structured parameters to verify the user's signature without central storage of passwords.

6. Axios JWT Refresh Interceptor

To prevent session expirations from interrupting user operations, the client HTTP client (Axios) incorporates a queue-based request interceptor.

// Simplified Axios Interceptor Flow
axios.interceptors.response.use(
  (response) => response,
  async (error) => {
    const originalRequest = error.config;
    if (error.response.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;
      
      // Pause incoming requests and queue them
      if (!isRefreshing) {
        isRefreshing = true;
        try {
          const { data } = await axios.post('/api/v1/user/refresh');
          const newAccessToken = data.accessToken;
          
          store.setAccessToken(newAccessToken);
          isRefreshing = false;
          
          // Replay all waiting requests with the updated token
          onRefreshed(newAccessToken);
          return axios(originalRequest);
        } catch (refreshError) {
          store.logout();
          return Promise.reject(refreshError);
        }
      }
      
      return new Promise((resolve) => {
        addSubscriber((token) => {
          originalRequest.headers['Authorization'] = 'Bearer ' + token;
          resolve(axios(originalRequest));
        });
      });
    }
    return Promise.reject(error);
  }
);

7. WebSocket Security & Sockets.io Core

WebSocket channels must be protected with short-lived tokens. The connection setup requires an authentication handshake before any events are processed.

• Transport Limit: Configured to use only transports: ["websocket"].
• Connection Handshake: On initial connection, the client must trigger the register event with a valid JWT token.
• Security Disconnect: If the server detects that the JWT has expired, it emits an auth_error code TOKEN_EXPIRED and forcefully closes the socket.
• Automatic Recovery: Upon receiving auth_error, the client handles the exception by requesting a refreshed JWT via the API, re-establishes the socket connection, and registers again.

8. Cryptographic Summary Table

A high-level reference of cryptographic algorithms and parameters implemented across the SatoLink system, in alignment with NIST standards.