TAuth SDK

Rust library for integrating applications with TAuth and MTP.

The SDK handles app key material, TAuth login URLs, callback parsing, Omikron lookup, authenticated MTP connections, and loading/saving user-specific app data.

Requirements

• Rust 1.95+
• A TAuth app identifier, usually your app domain
• An MTP key pair generated by this library
• A public callback URL in your application

Install

[dependencies]
tauth-sdk = { git = "https://git.methanium.net/tensamin/tauth-sdk.git" }
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Generate App Keys

Run this once, store the private key securely, and publish the public key where TAuth expects app verification data.

use tauth_sdk::generate_key_pair;

fn main() {
    let keys = generate_key_pair();

    println!("private: {}", keys.private);
    println!("public:  {}", keys.public);
}

Keys are base64-encoded MTP key material. Do not expose the private key.

Create A Client

use tauth_sdk::{TAuthClient, TAuthConfig};

let client = TAuthClient::from_config(
    TAuthConfig::new(
        "my.cool.app",
        "https://my.cool.app/tauth/callback",
        std::env::var("TAUTH_PRIVATE_KEY")?,
    )
    .frontend_url("https://tauth.tensamin.net/login"),
)?;

For the default TAuth frontend, this shorter form is equivalent:

let client = TAuthClient::new(
    "my.cool.app",
    "https://my.cool.app/tauth/callback",
    std::env::var("TAUTH_PRIVATE_KEY")?,
)?;

Start Login

Redirect the user to client.auth_url(None) from your web handler.

let login_url = client.auth_url(None);

The URL includes:

• identifier: your app identifier
• redirect: your callback URL
• public_key: your app MTP public key bundle
• challenge: optional caller-supplied challenge

Handle Callback

In your callback route, parse the full callback URL and persist the returned user_id and session_id for your user.

let callback = client.parse_callback(full_callback_url)?;

save_session(callback.user_id, callback.session_id).await?;

AuthCallback contains:

pub struct AuthCallback {
    pub user_id: u64,
    pub session_id: u64,
    pub challenge: Option<String>,
    pub original_challenge: Option<String>,
    pub host_public_key: Option<String>,
}

Connect To TAuth Data Over MTP

If the callback or your application already has the Omikron host public key, pass it explicitly:

let session = client
    .connect_session(callback.user_id, callback.session_id, host_public_key)
    .await?;

If the Omikron API returns a public_key, the SDK can look it up automatically:

let session = client.session_from_callback(&callback).await?;

The connection uses MTP authenticated login with your app keyring and the Omikron host public key.

Load And Save App Data

Use serde types for application data:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct AppData {
    name: String,
    value: String,
}

let data: AppData = session.load().await?;

session
    .save(&AppData {
        name: "example".into(),
        value: "updated".into(),
    })
    .await?;

Raw JSON is also supported:

let data = session.load_json().await?;
session.save_json(&data).await?;

Other Helpers

Fetch a TAuth user profile:

let user = client.user(callback.user_id).await?;

Connect directly to a known Omikron URL:

let connection = client
    .connect_to_omikron(user_id, session_id, "https://omikron.example:4433", host_public_key)
    .await?;

Use lower-level MTP connection helpers when needed:

let value = tauth_sdk::load_json(&connection).await?;
tauth_sdk::save_json(&connection, &value).await?;

MTP Type Map

This crate compiles an MTP type map for TAuth app data messages:

• LoadAppData
• LoadAppDataResponse
• SaveAppData
• SaveAppDataResponse
• AppData

The map lives in type-maps.yaml and is wired through .cargo/config.toml using MTP_TYPE_MAPS.

Development

cargo test
cargo build --release