talon-auth

talon-auth

Add login to any website. Passwordless sign up, sign in, social logins, and user management even without a server. Works with any framework, any runtime, plain HTML and it's offline-friendly.

Quick Start

The fastest way to integrate Talon Auth is with the MCP server. Add the following to your MCP configuration:

{
  "mcpServers": {
    "talon": {
      "command": "npx",
      "args": ["-y", "talon-mcp"]
    }
  }
}

Or use the login component directly in any HTML page:

<script type="module" src="https://esm.sh/talon-auth/login"></script>
<talon-login id="login" app-id="your-app-id"></talon-login>

Sign up at talon.codes to get your app ID.

Installation

npm install talon-auth

Client Usage

Browser

import { createClient } from 'talon-auth'

const auth = createClient({ appId: 'your-app-id' })

// Get the current user (fetches a fresh token)
const user = await auth.getUser()

// Get an access token
const token = await auth.getAccessToken()

// Get an authorization header for API calls
const header = await auth.getHeader()
// => "Bearer <token>"

// Log out the current device
await auth.logout()

In the browser, device keys are stored as non-extractable CryptoKey objects in IndexedDB so they cannot be read by injected scripts.

Node.js / Deno / Bun

For server-side or CLI usage, provide a FileStore:

import fs from 'node:fs/promises'
import { createClient, createFileStore } from 'talon-auth'

const auth = createClient({
  appId: 'your-app-id',
  store: createFileStore(fs, '.talon-auth.json'),
})

const user = await auth.getUser()

Multiple Devices

A single client can manage multiple devices (e.g. different browser profiles or accounts):

// List all devices for this app
const devices = await auth.listDevices()
// => [{ deviceId: "did:key:...", user: { id, email } }]

// Switch to a specific device
await auth.setDevice(devices[0].deviceId)

// Create a new device
await auth.createDevice()

Server-Side Token Verification

Verify access tokens on your backend with createVerifier:

import { createVerifier } from 'talon-auth'

const verifier = createVerifier({ appId: 'your-app-id' })

// Verify a Bearer token from an Authorization header
const { user, payload } = await verifier.verifyHeader(request.headers.get('Authorization'))
// user => { id: "...", email: "..." }

// Or verify a raw token string
const result = await verifier.verify(token)

Custom Stores

The client accepts any object implementing the KvStore interface:

interface KvStore<T> {
  getItem(key: string): Promise<T | null>
  setItem(key: string, value: T): Promise<void>
  removeItem(key: string): Promise<void>
  getAll(): Promise<T[]>
}

Built-in stores:

• createIndexedDbStore() - Browser default. Supports non-extractable CryptoKeys.
• createFileStore(fs, path) - File-based storage for Node.js/Deno/Bun.
• createMemoryStore() - In-memory, useful for testing.

Login Component

The <talon-login> web component handles the full passwordless and social login flow. Import it from the talon-auth/login entry point:

import 'talon-auth/login'

Or load it from a CDN:

<script type="module" src="https://esm.sh/talon-auth/login"></script>

Then use it in your HTML:

<talon-login app-id="your-app-id"></talon-login>

The component supports 20+ theme presets via the Talon Auth dashboard.

License

MIT