75 lines
2.2 KiB
Markdown
75 lines
2.2 KiB
Markdown
# TypeScript TAuth SDK
|
|
|
|
TypeScript SDK for TAuth-based login and explicit transport session management.
|
|
|
|
This SDK starts a local HTTP callback server, verifies a challenge, and gives you explicit control over TTP connections per `userId:sessionId`.
|
|
|
|
## Requirements
|
|
|
|
- A modern version of Bun
|
|
- A domain with TXT record support
|
|
- App x448 key pair (`privateKey`, `publicKey`) (can be generated)
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add https://git.methanium.net/tensamin/tauth-sdk/archive/0.0.2.tar.gz
|
|
```
|
|
|
|
## Generate an app key pair
|
|
|
|
Use the built-in helper once and store the keys securely:
|
|
|
|
```ts
|
|
import { generateKeyPair } from "@tensamin/tauth-sdk";
|
|
|
|
const keys = generateKeyPair();
|
|
console.log(keys.private);
|
|
console.log(keys.public);
|
|
```
|
|
|
|
## Add the TXT record
|
|
|
|
Add a TXT record at `tauth.your.domain` with your app public key as the value (base64 format). This is used to verify that your app is authorized for your domain.
|
|
|
|
## Basic usage
|
|
|
|
```ts
|
|
import z from "zod";
|
|
import { TAuthClient } from "@tensamin/tauth-sdk";
|
|
|
|
const client = new TAuthClient({
|
|
frontendUrl: "http://localhost:3000",
|
|
identifier: "your-app-identifier",
|
|
privateKey: "<APP_PRIVATE_KEY_BASE64>",
|
|
publicKey: "<APP_PUBLIC_KEY_BASE64>",
|
|
saveSession: async (userId, sessionId) => {
|
|
// You must persist the session id yourself (for example in a database).
|
|
// Treat the session id like a password!
|
|
console.log("Save session", { userId, sessionId });
|
|
},
|
|
redirectUrl: "http://localhost:7878/callback",
|
|
appData: z.object({
|
|
my: z.string(),
|
|
cool: z.string(),
|
|
data: z.string(),
|
|
}),
|
|
httpServer: {
|
|
hostname: "localhost",
|
|
port: 7878,
|
|
},
|
|
});
|
|
```
|
|
|
|
## Auth endpoints exposed by the SDK
|
|
|
|
- `GET /auth`: Redirects user to TAuth frontend
|
|
- `GET /callback`: Handles challenge flow and invokes your `saveSession(userId, sessionId)` callback
|
|
|
|
## Connection management
|
|
|
|
- Use `client.createTTP(userId, sessionId, omikronUrl)` when you want a persistent/manual TTP connection.
|
|
- Use `client.loadData(userId, sessionId)` for loading user specific application data.
|
|
- Use `client.saveData(userId, sessionId)` for saving user specific application data.
|
|
|
|
These endpoints need to be exposed behind some kind of http proxy to apply ssl
|