auth.rs

Overview

This file implements a token-based authorization mechanism designed to authenticate external messages within the system. It provides the creation, verification, and authorization of cryptographic tokens tied to specific token issuers, which represent wallet owners of certain blockchain-related contracts (BM and BK wallets). The tokens use ed25519 signatures to ensure integrity and authenticity. The file also manages caching of signing public keys to optimize performance and includes runtime flags to enable or disable authentication dynamically.

The core components include:

Entities and Structures

TokenIssuer

#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
#[serde(rename_all = "snake_case")]
pub enum TokenIssuer {
    Bm(String),
    Bk(String),
}

Token

#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct Token {
    pub unsigned: String, // UNIX timestamp in ms until which the token remains valid
    pub signature: String, // Hex-encoded ed25519 signature of `unsigned`
    pub issuer: TokenIssuer,
}

TokenVerificationResult

#[derive(Debug, PartialEq, Eq)]
pub enum TokenVerificationResult {
    Ok,
    TokenMalformed,
    InvalidSignature,
    Expired,
}

AccountRequest

pub struct AccountRequest {
    pub address: String,
    pub response: oneshot::Sender<anyhow::Result<Option<tvm_block::Account>>>,
}

WalletAddress

#[derive(Deserialize)]
struct WalletAddress {
    wallet: String,
}

Constants and Globals

Key Functions and Methods

Token::new(secret: &str, issuer: TokenIssuer) -> Result<Self, anyhow::Error>

Creates a new Token by signing the expiration timestamp with the provided secret key.

let token = Token::new(&secret_hex_key, TokenIssuer::Bm("bm_pubkey".to_string()))?;

Token::verify(&self, signing_pubkey: Option<String>) -> TokenVerificationResult

Verifies the token's signature and validity against the provided signing public key.

let result = token.verify(Some(public_hex_key));
match result {
    TokenVerificationResult::Ok => println!("Valid token"),
    _ => println!("Invalid token"),
}

Token::authorize(&self, account_request_tx: mpsc::Sender<AccountRequest>) -> TokenVerificationResult

Performs asynchronous authorization by retrieving the signing public key for the issuer and verifying the token.

async fn request_account(address: &str, account_request_tx: mpsc::Sender<AccountRequest>) -> anyhow::Result<Option<tvm_block::Account>>

Asynchronously requests a blockchain account for a given address via the provided channel.

async fn get_signing_pubkey(issuer: &TokenIssuer, account_request_tx: mpsc::Sender<AccountRequest>) -> anyhow::Result<Option<String>>

Retrieves and caches the signing public key associated with a TokenIssuer.

Authentication Control Functions

Implementation Details and Algorithms

Interaction with Other Modules

Visual Diagram

classDiagram
class TokenIssuer {
<<enum>>
+Bm(pubkey: String)
+Bk(pubkey: String)
}
class Token {
+unsigned: String
+signature: String
+issuer: TokenIssuer
+new(secret: &str, issuer: TokenIssuer) Token
+verify(signing_pubkey: Option<String>) TokenVerificationResult
+authorize(account_request_tx: Sender<AccountRequest>) async TokenVerificationResult
}
class AccountRequest {
+address: String
+response: oneshot::Sender<Result<Option<Account>>>
}
class TokenVerificationResult {
<<enum>>
+Ok
+TokenMalformed
+InvalidSignature
+Expired
}
Token *-- TokenIssuer: uses
Token ..> TokenVerificationResult: returns
Token --> AccountRequest: interacts via
AccountRequest ..> "tvm_block::Account": async fetch

This diagram illustrates the relationships between key structs and enums in this file, showing how Token depends on TokenIssuer, produces TokenVerificationResult, and interacts asynchronously with AccountRequest to fetch blockchain account data.

Testing

Environment Variables and Runtime Flags

References