Low-level Server-Side SDK

The Virto Server-Side SDK provides functionality specifically designed for server environments. Unlike the client-side SDK, these functions do not depend on browser APIs and can be executed in a Node.js environment.

Configuration

import ServerSDK from '@virtonetwork/sdk/server';

const serverSdk = new ServerSDK({
  federate_server: 'http://your-federate-server.com/api',
  provider_url: 'ws://your-blockchain-provider:12281',
  config: {
    wallet: 'polkadotjs',
    jwt: {
      secret: 'your-jwt-secret',
      expiresIn: '1h'  // Optional, defaults to '10m'
    }
  }
});

Auth Methods

The serverSdk.auth object provides the following methods for handling authentication on the server side:

completeRegistration(preparedData)

Completes the user registration process on the server side after registration data has been prepared by the client.

Parameters:

  • preparedData: Object containing the registration data prepared by the client

    {
  userId: string,          // The unique identifier for the user
  attestationResponse: {   // WebAuthn credential data from client
    id: string,
    rawId: string,
    type: string,
    response: {
      attestationObject: string,
      clientDataJSON: string
    }
  },
  blockNumber: number      // The blockchain block number for registration
}

Returns: Promise that resolves to the server's response to the registration.

Example:

const clientPreparedData = /* data received from client */;

try {
  const result = await serverSdk.auth.completeRegistration(clientPreparedData);
  console.log(`User registered successfully: ${result.address}`);
} catch (error) {
  console.error("Registration failed:", error.message);
}

completeConnection(preparedData)

Completes the connection process on the server side after authentication data has been prepared by the client. Creates a session for the user and returns a JWT token if configured.

Parameters:

  • preparedData: Object containing the connection data prepared by the client

    {
  userId: string,          // The unique identifier for the user
  assertionResponse: {     // WebAuthn assertion response from client
    id: string,
    rawId: string,
    type: string,
    response: {
      authenticatorData: string,
      clientDataJSON: string,
      signature: string
    }
  },
  blockNumber: number      // The blockchain block number for connection
}

Returns: Promise with the server's response, session information, and JWT token (if configured).

Example:

const clientPreparedData = /* data received from client */;

try {
  const result = await serverSdk.auth.completeConnection(clientPreparedData);
  console.log(`User connected successfully: ${result.session.address}`);
  console.log(`JWT token: ${result.token}`);
} catch (error) {
  console.error("Connection failed:", error.message);
}

signWithToken(token, command)

Signs a blockchain extrinsic after verifying the provided JWT token.

Parameters:

  • token: String - The JWT token to verify

  • command: Object containing the extrinsic details

    {
  hex: string,    // Required: Hexadecimal representation of the extrinsic
  url: string,    // Optional: URL endpoint for the extrinsic
  body: any       // Optional: Additional data for the request
}

Returns: Promise with the signing result including user ID, signed extrinsic, and original command.

Example:

const token = /* JWT token received from client */;
const extrinsic = "0x1234..."; // Hex representation of the extrinsic

try {
  const signed = await serverSdk.auth.signWithToken(token, {
    hex: extrinsic
  });
  
  console.log("User ID:", signed.userId);
} catch (error) {
  if (error.code === "E_JWT_EXPIRED") {
    console.error("Token has expired, user needs to reconnect");
  } else {
    console.error("Signing error:", error.message);
  }
}

verifyToken(token)

Verifies a JWT token and returns the decoded payload if valid.

Parameters:

  • token: String - The JWT token to verify

Returns: The decoded token payload if valid.

Example:

const token = /* JWT token received from client */;

try {
  const payload = serverSdk.auth.verifyToken(token);
  console.log(`Token valid for user: ${payload.userId}`);
  console.log(`User address: ${payload.address}`);
  console.log(`Token expires at: ${new Date(payload.exp * 1000)}`);
} catch (error) {
  if (error.code === "E_JWT_EXPIRED") {
    console.error("Token has expired");
  } else if (error.code === "E_JWT_INVALID") {
    console.error("Token is invalid");
  } else {
    console.error("Token verification failed:", error.message);
  }
}

isRegistered(userId)

Checks if a user is registered with the federate server.

Parameters:

  • userId: String - The unique identifier for the user

Returns: Promise with a boolean indicating if the user is registered.

Example:

try {
  const registered = await serverSdk.auth.isRegistered("alice@example.com");
  if (registered) {
    console.log("User is already registered, proceed to connect");
  } else {
    console.log("User needs to register first");
  }
} catch (error) {
  console.error("Error checking registration status:", error.message);
}

Error Handling

All methods may throw errors that should be handled appropriately:

try {
  const result = await serverSdk.auth.completeConnection(preparedData);
  // Process successful result
} catch (error) {
  if (error.code === "E_CANT_GET_CREDENTIAL") {
    console.error("User wallet not found");
    // Prompt user to register
  } else if (error.code === "E_JWT_EXPIRED") {
    console.error("JWT token has expired");
    // Prompt user to reconnect
  } else {
    console.error("Error:", error.message);
  }
}

Common error codes include:

  • E_CANT_GET_CREDENTIAL: User wallet not found

  • E_NO_JWT_CONFIG: JWT configuration not provided

  • E_JWT_EXPIRED: Token has expired

  • E_JWT_INVALID: Invalid token

  • E_JWT_UNKNOWN: Token verification failed

  • E_SESSION_NOT_FOUND: Session not found for this token

  • E_ADDRESS_MISMATCH: Token address does not match session address

Sequence Diagram

PreviousLow-level Client-Side SDKNextAPI

Last updated