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('username', 'password'); // { type: 'basic', username, password }
Auth.jwt('<token>'); // { type: 'jwt', token }
Auth.none(); // { type: 'none' }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 Basic auth
Return Auth.basic(user, pass) when your app authenticates with username and
password. The SDK automatically exchanges those credentials for a JWT before
the first 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);
};Basic → JWT login upgrade
login() exchanges basic 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 internallyRefresh 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,
isNoAuth,
isAuthenticated,
} from '@kalamdb/client';buildAuthHeader() returns:
- basic →
Basic <base64(username:password)> - jwt →
Bearer <token> - none →
undefined
Used internally by queryWithFiles() for multipart uploads.