Authentication

@kalamdb/client models auth as a tagged union with type-safe constructors.

The same Auth and authProvider model is reused by createConsumerClient() in @kalamdb/consumer.

Auth modes

import { Auth } from '@kalamdb/client';
 
Auth.basic('user', 'password');     // { type: 'basic', user, password }
Auth.jwt('<token>');                // { type: 'jwt', token }

authProvider — the only auth option

All clients must provide an authProvider callback. The client resolves it during initialization, and the WASM transport uses it again for WebSocket connect/reconnect auth resolution, so token refresh stays centralized in one place.

import { createClient, Auth, type AuthProvider } from '@kalamdb/client';
 
const authProvider: AuthProvider = async () => {
  const token = await myApp.getOrRefreshJwt(); // your token store
  return Auth.jwt(token);
};
 
const client = createClient({
  url: 'http://localhost:8080',
  authProvider,
});

With user/password bootstrap

Return Auth.basic(user, pass) when your app starts from user/password credentials. The SDK only uses those credentials on POST /v1/api/auth/login and exchanges them for a JWT before the first authenticated query or WebSocket connection:

const client = createClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.basic('alice', 'Secret123!'),
});

With OAuth / SSO

Fetch and return a fresh JWT from your token endpoint:

const authProvider: AuthProvider = async () => {
  // Fetch a fresh JWT from your token endpoint
  const res = await fetch('/api/auth/token');
  const { access_token } = await res.json();
  return Auth.jwt(access_token);
};

User/password → JWT login upgrade

login() exchanges user/password credentials for a JWT. When the client was created with authProvider returning Auth.basic(...), the SDK calls this automatically before the first query or WebSocket connection. You can also call it manually:

const client = createClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.basic('alice', 'Secret123!'),
});
 
const login = await client.login();
console.log(login.access_token, login.refresh_token);
// client auth is now JWT internally

Refresh token

const refreshed = await client.refreshToken('<refresh_token>');
console.log(refreshed.access_token);

refreshToken() updates the internal auth to the new JWT token.

Auth helpers

import {
  buildAuthHeader,
  encodeBasicAuth,
  isBasicAuth,
  isJwtAuth,
  isAuthenticated,
} from '@kalamdb/client';

buildAuthHeader() returns:

• basic → throws, because user/password credentials are only valid for POST /v1/api/auth/login
• jwt → Bearer <token>

For basic, buildAuthHeader() throws because user/password credentials are only valid for POST /v1/api/auth/login.

Used internally by queryWithFiles() after the login exchange has produced JWT auth.