# 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

```toml
[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.

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

```rust
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://app.tensamin.net"),
)?;
```

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

```rust
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, session_id)` from your web handler. The `session_id` is a `u64` you generate (e.g. from the current time in milliseconds) — it is passed through the TAuth flow and returned in the callback so you can correlate the login with a pending session.

```rust
let session_id = std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH)
    .map(|d| d.as_millis() as u64)
    .unwrap_or(0);
let login_url = client.auth_url(None, session_id);
```

The URL includes:

- `identifier`: your app identifier
- `redirect`: your callback URL
- `public_key`: your app MTP public key bundle
- `sessionId`: the session ID you generated, passed through to the callback
- `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.

```rust
let callback = client.parse_callback(full_callback_url)?;

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

`AuthCallback` contains:

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

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

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

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

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

## Other Helpers

Fetch a TAuth user profile:

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

Connect directly to a known Omikron URL:

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

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

```bash
cargo test
cargo build --release
```