@butrauth/client

Tiny Node.js client for Butter Auth — OAuth 2.0 Authorization Code + PKCE, RS256 access tokens, Hive identity bridge.

Zero runtime dependencies. Node ≥ 18 (uses global fetch and node:crypto).

Install

npm install @butrauth/client

Usage

import { ButrAuthClient } from '@butrauth/client'

const butr = new ButrAuthClient({
  baseUrl: 'https://auth.okinoko.io',
  clientId: process.env.BUTRAUTH_CLIENT_ID,
  clientSecret: process.env.BUTRAUTH_CLIENT_SECRET
})

// 1. Build the redirect URL (in your /login handler)
const { url, codeVerifier, state } = butr.createAuthRequest({
  redirectUri: 'https://my-app.com/callback'
})
// → store `codeVerifier` in an httpOnly cookie or server session
// → res.redirect(url)

// 2. Exchange the code (in your /callback handler)
const tokens = await butr.exchangeCode({
  code: req.query.code,
  redirectUri: 'https://my-app.com/callback',
  codeVerifier // from the cookie/session
})
// → { accessToken, tokenType, expiresIn, username }

// 3. Verify the token whenever you need to authenticate a request
const claims = await butr.verifyAccessToken(tokens.accessToken)
// → { userId, hiveUsername, clientId, issuedAt, expiresAt }

The full HTTP contract is documented in ../INTEGRATION.md.

A runnable Express example lives in example.js.

API

new ButrAuthClient({ baseUrl, clientId, clientSecret })

client.createAuthRequest({ redirectUri, scope?, state? })

Returns { url, codeVerifier, state }. The caller must persist codeVerifier until exchangeCode runs.

client.exchangeCode({ code, redirectUri, codeVerifier })

Returns { accessToken, tokenType, expiresIn, username }. Throws ButrAuthError on any failure.

client.verifyAccessToken(token)

Verifies the RS256 JWT against Butter Auth's public key (cached for one hour) and returns the decoded claims. Throws ButrAuthError on bad signature, expiry, wrong audience, or wrong token type.

client.getPublicKey()

Returns the RSA public key (PEM). Mostly internal — call verifyAccessToken instead.

Broadcasting on the user's behalf

Butter Auth does not broadcast for you. The user grants posting authority to your service account on chain during the auth flow, and your backend uses its own posting WIF to sign and broadcast operations. See ../INTEGRATION.md.