# 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

```javascript
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

  ```javascript
  {
    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:**

```javascript
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

  ```javascript
  {
    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:**

```javascript
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

  ```javascript
  {
    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:**

```javascript
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:**

```javascript
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:**

```javascript
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:

```javascript
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&#x20;

<figure><img src="https://749265424-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMjfD3GsKmHDXEKTOXApi%2Fuploads%2FB24YxtSF3i5dKKxiUogL%2FSD-SDK.png?alt=media&#x26;token=c627b27e-d1ef-4318-990a-b0f4f5a34dc4" alt=""><figcaption></figcaption></figure>
