auth library

Authentication utilities for Kumiho SDK.

This library provides authentication support for the Kumiho Dart SDK, including:

  • Token loading from environment variables
  • Token loading from ~/.kumiho/kumiho_authentication.json (kumiho-cli)
  • Auto-refresh of expired tokens (opt-in)

Token Loading Priority

  1. KUMIHO_AUTH_TOKEN environment variable
  2. Firebase ID token from credentials file
  3. Control Plane token (if KUMIHO_USE_CONTROL_PLANE_TOKEN=true)

Auto-Refresh

Set KUMIHO_ENABLE_AUTO_REFRESH=true to enable automatic token refresh when credentials expire. The SDK will use the stored refresh token to obtain new ID tokens.

Environment Variables

Variable Description
KUMIHO_AUTH_TOKEN Primary auth token (overrides file)
KUMIHO_FIREBASE_ID_TOKEN Firebase-specific token
KUMIHO_CONFIG_DIR Custom config directory
KUMIHO_USE_CONTROL_PLANE_TOKEN Prefer CP token (true/false)
KUMIHO_ENABLE_AUTO_REFRESH Enable token auto-refresh (true/false)
KUMIHO_AUTH_TOKEN_GRACE_SECONDS Grace period before expiry (default: 300)
KUMIHO_FIREBASE_API_KEY Custom Firebase API key
KUMIHO_CONTROL_PLANE_URL Custom Control Plane base URL (preferred)
KUMIHO_CONTROL_PLANE_API_URL Custom CP base URL (legacy)

Usage

import 'package:kumiho/auth.dart';

// Simple token loading
final token = loadBearerToken();

// Token with source info
final result = loadBearerTokenWithSource();
print('Token from: ${result.source}');

// Auto-refresh credentials
final creds = await ensureValidCredentials();
if (creds != null) {
  print('Token valid: ${creds.isValid}');
}

Classes

AuthDefaults
Default values for authentication.
AuthEnvVars
Environment variable names for authentication.
KumihoCredentials
Cached credentials from the kumiho-cli authentication.
TokenLoadResult
Result of loading a token with metadata.
TokenRefreshResult
Result of a token refresh operation.

Functions

autoRefreshCredentials(KumihoCredentials? credentials, {bool forceRefresh = false}) → Future<KumihoCredentials?>
Auto-refreshes credentials if they're expired and auto-refresh is enabled.
exchangeForControlPlaneToken(String firebaseToken, {String? controlPlaneUrl}) → Future<({int expiresAt, String token})?>
Exchanges a Firebase ID token for a Control Plane JWT.
getConfigDir() → Directory
Gets the Kumiho configuration directory.
getCredentialsFile() → File
Gets the path to the credentials file.
loadBearerToken() → String?
Loads the bearer token for gRPC calls.
loadBearerTokenWithSource() → TokenLoadResult
Loads the bearer token with source information.
loadCredentials() → KumihoCredentials?
Reads cached credentials from the credentials file.
loadFirebaseToken() → String?
Loads the Firebase ID token for control-plane interactions.
refreshFirebaseToken(String apiKey, String refreshToken) → Future<TokenRefreshResult>
Refreshes a Firebase ID token using a refresh token.
saveCredentials(KumihoCredentials credentials) → void
Saves credentials to the credentials file.

Exceptions / Errors

TokenRefreshError
Exception thrown when token refresh fails.