@serafort/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Configuration options for initializing the Serafort SDK client.
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts. Default: 3 */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds. Default: 500ms */
+    initialDelayMs?: number;
+    /** Maximum retry delay in milliseconds. Default: 5000ms */
+    maxDelayMs?: number;
+}
+interface SerafortConfig {
+    /** Base URL of the Serafort IAM backend (e.g. "https://auth.acme.com" or "http://localhost:3333") */
+    endpoint?: string;
+    /** Alias for endpoint */
+    baseUrl?: string;
+    /** Client identifier for Machine-to-Machine (M2M) authentication */
+    clientId?: string;
+    /** Client secret for Machine-to-Machine (M2M) authentication */
+    clientSecret?: string;
+    /** Publishable key for client-side and B2B public operations (starts with pk_live_ or pk_test_) */
+    publishableKey?: string;
+    /** Domain identifier (e.g. "auth.acme.com") */
+    domain?: string;
+    /** Request timeout in milliseconds. Default: 10,000ms */
+    timeout?: number;
+    /** Custom retry policy configuration for network resilience */
+    retryPolicy?: RetryConfig;
+    /** Custom fetch function implementation (defaults to global fetch) */
+    fetch?: typeof fetch;
+}
+/**
+ * Resolved user security context decoded from a verified JWT token.
+ */
+interface UserContext {
+    /** The unique user identifier */
+    userId: string;
+    /** The tenant or organization identifier */
+    tenantId: string;
+    /** The primary email address of the user, if available */
+    email?: string;
+    /** Assigned roles (e.g. ["admin", "billing_manager"]) */
+    roles: string[];
+    /** Granted granular permissions (e.g. ["org:read", "billing:write"]) */
+    permissions: string[];
+    /** Raw decoded JWT payload claims */
+    claims: Record<string, unknown>;
+}
+/**
+ * OAuth2 token response payload from /oauth/token.
+ */
+interface OAuthTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+    refresh_token?: string;
+}
+/**
+ * Standard JSON Web Key (JWK) structure according to RFC 7517.
+ */
+interface JWK {
+    kty: string;
+    kid?: string;
+    use?: string;
+    alg?: string;
+    n?: string;
+    e?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    [key: string]: unknown;
+}
+/**
+ * Standard JSON Web Key Set (JWKS) structure according to RFC 7517.
+ */
+interface JWKS {
+    keys: JWK[];
+}
+/**
+ * Standard API error detail item.
+ */
+interface ApiErrorDetail {
+    field?: string;
+    message: string;
+    rule?: string;
+}
+/**
+ * Standard Serafort API response error envelope.
+ */
+interface ApiErrorEnvelope {
+    status: 'error';
+    error: {
+        code: string;
+        message: string;
+        status: number;
+        details?: ApiErrorDetail[];
+    };
+}
+
+declare class JwksClient {
+    private readonly jwksUrl;
+    private readonly fetchImpl;
+    private cachedKeys;
+    private lastFetchedAt;
+    private readonly cacheTtlMs;
+    constructor(config: SerafortConfig, cacheTtlMs?: number);
+    /**
+     * Retrieves the CryptoKey matching the key ID (kid) from cache, or fetches from the JWKS endpoint.
+     */
+    getVerificationKey(kid?: string, alg?: string): Promise<CryptoKey>;
+    /**
+     * Refreshes public keys from the JWKS endpoint and imports them as CryptoKeys.
+     */
+    refreshJwks(): Promise<void>;
+    /**
+     * Imports a raw JWK into a Web Crypto CryptoKey.
+     */
+    importJwk(key: JWK): Promise<CryptoKey>;
+}
+
+interface TokenValidationOptions {
+    /** Expected JWT issuer (iss) */
+    expectedIssuer?: string;
+    /** Expected JWT audience (aud) */
+    expectedAudience?: string;
+    /** Allowed clock tolerance in seconds (default: 60s) */
+    clockToleranceSeconds?: number;
+    /** If true, skips cryptographic signature verification (ONLY for offline dev/testing) */
+    skipSignatureCheck?: boolean;
+}
+declare class B2BModule {
+    readonly config: SerafortConfig;
+    private readonly jwksClient;
+    private readonly baseUrl;
+    constructor(config: SerafortConfig, jwksClient?: JwksClient);
+    /**
+     * Validates a JWT token locally: checks signature against cached JWKS, verifies expiration,
+     * issuer, and audience, and decodes claims into a strongly-typed UserContext.
+     */
+    validateToken(token: string, options?: TokenValidationOptions): Promise<UserContext>;
+    /**
+     * Checks if the user context contains a specific granular permission.
+     * Supports wildcard matching (e.g. "org:*" matches "org:read").
+     */
+    hasPermission(userContext: UserContext, requiredPermission: string): boolean;
+    /**
+     * Checks if the user context contains a specific role.
+     */
+    hasRole(userContext: UserContext, requiredRole: string): boolean;
+    /**
+     * Constructs the Enterprise SSO Login URL for a specific tenant/organization.
+     */
+    getLoginUrl(tenantId: string, redirectUri: string, options?: {
+        state?: string;
+        connection?: string;
+    }): string;
+    /**
+     * Maps un-enveloped JWT claims to standard UserContext.
+     */
+    private mapClaimsToUserContext;
+}
+
+interface CachedToken {
+    accessToken: string;
+    expiresAt: number;
+    scope?: string;
+}
+/**
+ * High-concurrency, Promise-safe in-memory cache for Machine-to-Machine (M2M) access tokens.
+ * Automatically refreshes before expiration and coalesces concurrent refresh requests
+ * to avoid thundering-herd problems against the IAM server.
+ */
+declare class M2MTokenCache {
+    private cache;
+    private inFlightRequests;
+    /**
+     * Refresh window buffer in seconds (default: 300s = 5 minutes).
+     * A token expiring within this window will be refreshed proactively.
+     */
+    private readonly refreshBufferSeconds;
+    constructor(refreshBufferSeconds?: number);
+    /**
+     * Retrieves a cached token if valid, or invokes the refresher function.
+     * If a fetch is already in flight for the given cache key, coalesces into that existing promise.
+     */
+    getOrFetch(cacheKey: string, refresher: () => Promise<{
+        accessToken: string;
+        expiresIn: number;
+        scope?: string;
+    }>, force?: boolean): Promise<string>;
+    /**
+     * Invalidates cached token for a specific cache key or clears all.
+     */
+    invalidate(cacheKey?: string): void;
+    /**
+     * Returns current cached item metadata (for diagnostics and testing).
+     */
+    get(cacheKey: string): CachedToken | undefined;
+}
+
+declare class M2MModule {
+    private readonly config;
+    private readonly cache;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(config: SerafortConfig, cache?: M2MTokenCache);
+    /**
+     * Retrieves a valid M2M access token.
+     * Pulls from memory cache if valid and outside the refresh buffer.
+     * If nearing expiration or missing, transparently requests a new token.
+     */
+    getAccessToken(scopes?: string[]): Promise<string>;
+    /**
+     * Forces a refresh of the access token, bypassing the cache.
+     * Useful when an API endpoint returns 401 due to early revocation.
+     */
+    forceRefreshToken(scopes?: string[]): Promise<string>;
+    /**
+     * Clears the in-memory token cache.
+     */
+    clearCache(): void;
+    /**
+     * Performs the HTTP request to the OAuth2 token endpoint using Client Credentials grant.
+     */
+    private fetchTokenNetwork;
+}
+
+/**
+ * Unified Serafort SDK Client.
+ * Provides Machine Identity (M2M) token caching and B2B User Identity / RBAC capabilities.
+ */
+declare class SerafortClient {
+    readonly config: SerafortConfig;
+    readonly m2m: M2MModule;
+    readonly b2b: B2BModule;
+    constructor(config: SerafortConfig);
+    /**
+     * Helper shortcut to retrieve an M2M access token.
+     */
+    getAccessToken(scopes?: string[]): Promise<string>;
+    /**
+     * Helper shortcut to validate a JWT token and decode its UserContext.
+     */
+    validateToken(token: string): Promise<UserContext>;
+}
+
+/**
+ * Base exception class for all Serafort SDK errors.
+ */
+declare class SerafortError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: ApiErrorDetail[];
+    constructor(message: string, code?: string, status?: number, details?: ApiErrorDetail[]);
+}
+/**
+ * Authentication failed (invalid credentials, expired session, invalid JWT signature).
+ */
+declare class AuthenticationError extends SerafortError {
+    constructor(message?: string, code?: string, details?: ApiErrorDetail[]);
+}
+/**
+ * Multi-Factor Authentication required to complete access.
+ */
+declare class MfaRequiredError extends SerafortError {
+    readonly challengeId?: string;
+    readonly supportedMethods?: string[];
+    constructor(message?: string, challengeId?: string, supportedMethods?: string[], details?: ApiErrorDetail[]);
+}
+/**
+ * Request payload failed validation checks.
+ */
+declare class ValidationError extends SerafortError {
+    constructor(message?: string, details?: ApiErrorDetail[]);
+}
+/**
+ * Rate limit exceeded (HTTP 429).
+ */
+declare class RateLimitError extends SerafortError {
+    readonly retryAfterSeconds?: number;
+    constructor(message?: string, retryAfterSeconds?: number, details?: ApiErrorDetail[]);
+}
+/**
+ * Requested resource or tenant does not exist.
+ */
+declare class NotFoundError extends SerafortError {
+    constructor(message?: string, code?: string, details?: ApiErrorDetail[]);
+}
+/**
+ * Network failure, client-side timeout, or host unreachable.
+ */
+declare class NetworkError extends SerafortError {
+    constructor(message?: string, cause?: unknown);
+}
+
+interface DecodedJwt<T = Record<string, unknown>> {
+    header: {
+        alg: string;
+        typ?: string;
+        kid?: string;
+        [key: string]: unknown;
+    };
+    payload: T;
+    signature: Uint8Array;
+    signingInput: Uint8Array;
+}
+/**
+ * Decodes a base64url-encoded string into raw Uint8Array bytes.
+ */
+declare function base64UrlToBytes(str: string): Uint8Array;
+/**
+ * Decodes a base64url-encoded string into a UTF-8 string.
+ */
+declare function base64UrlDecode(str: string): string;
+/**
+ * Parses and separates the JWT into header, payload, signature, and signing input.
+ */
+declare function parseJwt<T = Record<string, unknown>>(token: string): DecodedJwt<T>;
+
+interface ExecuteWithRetryOptions {
+    retryConfig?: RetryConfig;
+    signal?: AbortSignal;
+}
+/**
+ * Executes an async operation with exponential backoff and jitter on retryable errors
+ * (HTTP 429, 502, 503, 504, and transient network errors).
+ */
+declare function executeWithRetry<T>(fn: () => Promise<T>, options?: ExecuteWithRetryOptions): Promise<T>;
+
+export { type ApiErrorDetail, type ApiErrorEnvelope, AuthenticationError, B2BModule, type JWK, type JWKS, JwksClient, M2MModule, M2MTokenCache, MfaRequiredError, NetworkError, NotFoundError, type OAuthTokenResponse, RateLimitError, type RetryConfig, SerafortClient, type SerafortConfig, SerafortError, type TokenValidationOptions, type UserContext, ValidationError, base64UrlDecode, base64UrlToBytes, executeWithRetry, parseJwt };