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

1import { Auth } from '@kalamdb/client';2 3Auth.basic('user', 'password');     // { type: 'basic', user, password }4Auth.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.

1import { createClient, Auth, type AuthProvider } from '@kalamdb/client';2 3const authProvider: AuthProvider = async () => {4  const token = await myApp.getOrRefreshJwt(); // your token store5  return Auth.jwt(token);6};7 8const client = createClient({9  url: 'http://localhost:2900',10  authProvider,11});

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:

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

With OAuth / SSO

Fetch and return a fresh JWT from your token endpoint:

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

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:

1const client = createClient({2  url: 'http://localhost:2900',3  authProvider: async () => Auth.basic('alice', 'Secret123!'),4});5 6const login = await client.login();7console.log(login.access_token, login.refresh_token);8// client auth is now JWT internally

Refresh token

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

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

Auth helpers

1import {2  buildAuthHeader,3  encodeBasicAuth,4  isBasicAuth,5  isJwtAuth,6  isAuthenticated,7} 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.