@vybestack/llxprt-code-auth 0.10.0-nightly.260613.1adad3b34

package/dist/src/oauth-errors.js

@@ -0,0 +1,465 @@
+/* eslint-disable no-console */
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/* eslint-disable complexity -- Phase 5: legacy core boundary retained while larger decomposition continues. */
+/**
+ * OAuth Error Handling System
+ *
+ * Provides comprehensive error classification, user-friendly messaging,
+ * and recovery mechanisms for OAuth providers.
+ */
+/**
+ * OAuth error categories for classification and handling
+ */
+export var OAuthErrorCategory;
+(function (OAuthErrorCategory) {
+    /** User must take action (re-authenticate, grant permissions) */
+    OAuthErrorCategory["USER_ACTION_REQUIRED"] = "user_action_required";
+    /** Network or temporary service issues that can be retried */
+    OAuthErrorCategory["TRANSIENT"] = "transient";
+    /** System issues (file permissions, storage problems) */
+    OAuthErrorCategory["SYSTEM"] = "system";
+    /** Critical security or data corruption issues */
+    OAuthErrorCategory["CRITICAL"] = "critical";
+    /** Configuration or setup problems */
+    OAuthErrorCategory["CONFIGURATION"] = "configuration";
+})(OAuthErrorCategory || (OAuthErrorCategory = {}));
+/**
+ * Specific OAuth error types with detailed classification
+ */
+export var OAuthErrorType;
+(function (OAuthErrorType) {
+    // User-actionable errors
+    OAuthErrorType["AUTHENTICATION_REQUIRED"] = "authentication_required";
+    OAuthErrorType["AUTHORIZATION_EXPIRED"] = "authorization_expired";
+    OAuthErrorType["INSUFFICIENT_PERMISSIONS"] = "insufficient_permissions";
+    OAuthErrorType["USER_CANCELLED"] = "user_cancelled";
+    OAuthErrorType["INVALID_CREDENTIALS"] = "invalid_credentials";
+    // Transient errors
+    OAuthErrorType["NETWORK_ERROR"] = "network_error";
+    OAuthErrorType["SERVICE_UNAVAILABLE"] = "service_unavailable";
+    OAuthErrorType["RATE_LIMITED"] = "rate_limited";
+    OAuthErrorType["TIMEOUT"] = "timeout";
+    // System errors
+    OAuthErrorType["STORAGE_ERROR"] = "storage_error";
+    OAuthErrorType["FILE_PERMISSIONS"] = "file_permissions";
+    OAuthErrorType["CORRUPTED_DATA"] = "corrupted_data";
+    // Critical errors
+    OAuthErrorType["SECURITY_VIOLATION"] = "security_violation";
+    OAuthErrorType["MALFORMED_TOKEN"] = "malformed_token";
+    // Configuration errors
+    OAuthErrorType["INVALID_CLIENT_ID"] = "invalid_client_id";
+    OAuthErrorType["INVALID_ENDPOINT"] = "invalid_endpoint";
+    OAuthErrorType["MISSING_CONFIGURATION"] = "missing_configuration";
+    // Generic fallback
+    OAuthErrorType["UNKNOWN"] = "unknown";
+})(OAuthErrorType || (OAuthErrorType = {}));
+/**
+ * Default retry configuration for transient errors
+ */
+export const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    baseDelayMs: 1000,
+    backoffMultiplier: 2,
+    maxDelayMs: 30000,
+    jitter: true,
+};
+/**
+ * Comprehensive OAuth error with classification and user guidance
+ */
+export class OAuthError extends Error {
+    category;
+    type;
+    provider;
+    userMessage;
+    actionRequired;
+    isRetryable;
+    retryAfterMs;
+    technicalDetails;
+    originalError;
+    constructor(type, provider, message, options = {}) {
+        super(message);
+        this.name = 'OAuthError';
+        this.type = type;
+        this.provider = provider;
+        this.category = this.categorizeError(type);
+        this.isRetryable = this.determineRetryability(type);
+        this.userMessage =
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional falsy coalescing: empty string userMessage should fall back to generated
+            options.userMessage || this.generateUserMessage(type, provider);
+        this.actionRequired =
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional falsy coalescing: empty string actionRequired should fall back to generated
+            options.actionRequired || this.generateActionRequired(type, provider);
+        this.retryAfterMs = options.retryAfterMs ?? null;
+        this.technicalDetails = options.technicalDetails ?? {};
+        this.originalError = options.originalError ?? null;
+    }
+    /**
+     * Categorizes error type into handling categories
+     */
+    categorizeError(type) {
+        switch (type) {
+            case OAuthErrorType.AUTHENTICATION_REQUIRED:
+            case OAuthErrorType.AUTHORIZATION_EXPIRED:
+            case OAuthErrorType.INSUFFICIENT_PERMISSIONS:
+            case OAuthErrorType.USER_CANCELLED:
+            case OAuthErrorType.INVALID_CREDENTIALS:
+                return OAuthErrorCategory.USER_ACTION_REQUIRED;
+            case OAuthErrorType.NETWORK_ERROR:
+            case OAuthErrorType.SERVICE_UNAVAILABLE:
+            case OAuthErrorType.RATE_LIMITED:
+            case OAuthErrorType.TIMEOUT:
+                return OAuthErrorCategory.TRANSIENT;
+            case OAuthErrorType.STORAGE_ERROR:
+            case OAuthErrorType.FILE_PERMISSIONS:
+            case OAuthErrorType.CORRUPTED_DATA:
+                return OAuthErrorCategory.SYSTEM;
+            case OAuthErrorType.SECURITY_VIOLATION:
+            case OAuthErrorType.MALFORMED_TOKEN:
+                return OAuthErrorCategory.CRITICAL;
+            case OAuthErrorType.INVALID_CLIENT_ID:
+            case OAuthErrorType.INVALID_ENDPOINT:
+            case OAuthErrorType.MISSING_CONFIGURATION:
+                return OAuthErrorCategory.CONFIGURATION;
+            default:
+                return OAuthErrorCategory.SYSTEM;
+        }
+    }
+    /**
+     * Determines if error type is retryable
+     */
+    determineRetryability(type) {
+        switch (type) {
+            case OAuthErrorType.NETWORK_ERROR:
+            case OAuthErrorType.SERVICE_UNAVAILABLE:
+            case OAuthErrorType.TIMEOUT:
+                return true;
+            case OAuthErrorType.RATE_LIMITED:
+                return true; // But with specific delay
+            default:
+                return false;
+        }
+    }
+    /**
+     * Generates user-friendly error message
+     */
+    generateUserMessage(type, provider) {
+        const providerName = provider.charAt(0).toUpperCase() + provider.slice(1);
+        switch (type) {
+            case OAuthErrorType.AUTHENTICATION_REQUIRED:
+                return `You need to sign in to ${providerName} to continue.`;
+            case OAuthErrorType.AUTHORIZATION_EXPIRED:
+                return `Your ${providerName} session has expired. Please sign in again.`;
+            case OAuthErrorType.INSUFFICIENT_PERMISSIONS:
+                return `${providerName} access was denied. Please grant the required permissions.`;
+            case OAuthErrorType.USER_CANCELLED:
+                return `${providerName} authentication was cancelled.`;
+            case OAuthErrorType.INVALID_CREDENTIALS:
+                return `The ${providerName} credentials are invalid. Please sign in again.`;
+            case OAuthErrorType.NETWORK_ERROR:
+                return `Unable to connect to ${providerName}. Please check your internet connection.`;
+            case OAuthErrorType.SERVICE_UNAVAILABLE:
+                return `${providerName} is currently unavailable. Please try again later.`;
+            case OAuthErrorType.RATE_LIMITED:
+                return `Too many requests to ${providerName}. Please wait a moment and try again.`;
+            case OAuthErrorType.TIMEOUT:
+                return `Connection to ${providerName} timed out. Please try again.`;
+            case OAuthErrorType.STORAGE_ERROR:
+                return `Unable to save ${providerName} authentication data. Please check file permissions.`;
+            case OAuthErrorType.FILE_PERMISSIONS:
+                return `Permission denied when accessing ${providerName} authentication files.`;
+            case OAuthErrorType.CORRUPTED_DATA:
+                return `${providerName} authentication data is corrupted. Please sign in again.`;
+            case OAuthErrorType.SECURITY_VIOLATION:
+                return `${providerName} authentication failed due to a security issue.`;
+            case OAuthErrorType.MALFORMED_TOKEN:
+                return `${providerName} returned invalid authentication data. Please try again.`;
+            case OAuthErrorType.INVALID_CLIENT_ID:
+                return `${providerName} configuration error: invalid client ID.`;
+            case OAuthErrorType.INVALID_ENDPOINT:
+                return `${providerName} configuration error: invalid server endpoint.`;
+            case OAuthErrorType.MISSING_CONFIGURATION:
+                return `${providerName} is not properly configured.`;
+            default:
+                return `An unexpected error occurred with ${providerName} authentication.`;
+        }
+    }
+    /**
+     * Generates actionable guidance for users
+     */
+    generateActionRequired(type, provider) {
+        switch (type) {
+            case OAuthErrorType.AUTHENTICATION_REQUIRED:
+            case OAuthErrorType.AUTHORIZATION_EXPIRED:
+            case OAuthErrorType.INVALID_CREDENTIALS:
+                return `Run 'llxprt auth login ${provider}' to sign in again.`;
+            case OAuthErrorType.INSUFFICIENT_PERMISSIONS:
+                return `Grant the required permissions during ${provider} authentication.`;
+            case OAuthErrorType.USER_CANCELLED:
+                return `Complete the ${provider} authentication process to continue.`;
+            case OAuthErrorType.NETWORK_ERROR:
+                return 'Check your internet connection and try again.';
+            case OAuthErrorType.SERVICE_UNAVAILABLE:
+            case OAuthErrorType.RATE_LIMITED:
+            case OAuthErrorType.TIMEOUT:
+                return 'Wait a few minutes and try again.';
+            case OAuthErrorType.STORAGE_ERROR:
+            case OAuthErrorType.FILE_PERMISSIONS:
+                return 'Check that you have write permissions to ~/.llxprt directory.';
+            case OAuthErrorType.CORRUPTED_DATA:
+                return `Run 'llxprt auth logout ${provider}' then sign in again.`;
+            case OAuthErrorType.SECURITY_VIOLATION:
+                return 'Contact support if this problem persists.';
+            case OAuthErrorType.MALFORMED_TOKEN:
+                return `Sign out and back in to ${provider}.`;
+            case OAuthErrorType.INVALID_CLIENT_ID:
+            case OAuthErrorType.INVALID_ENDPOINT:
+            case OAuthErrorType.MISSING_CONFIGURATION:
+                return 'Check your application configuration.';
+            default:
+                return null;
+        }
+    }
+    /**
+     * Creates a sanitized version of the error for logging
+     */
+    toLogEntry() {
+        return {
+            type: this.type,
+            category: this.category,
+            provider: this.provider,
+            isRetryable: this.isRetryable,
+            retryAfterMs: this.retryAfterMs,
+            message: this.message,
+            userMessage: this.userMessage,
+            actionRequired: this.actionRequired,
+            technicalDetails: this.technicalDetails,
+            stack: this.stack,
+            originalError: this.originalError
+                ? {
+                    name: this.originalError.name,
+                    message: this.originalError.message,
+                    stack: this.originalError.stack,
+                }
+                : null,
+        };
+    }
+}
+/**
+ * Error factory for common OAuth error scenarios
+ */
+export class OAuthErrorFactory {
+    /**
+     * Creates an authentication required error
+     */
+    static authenticationRequired(provider, details) {
+        return new OAuthError(OAuthErrorType.AUTHENTICATION_REQUIRED, provider, `Authentication required for ${provider}`, { technicalDetails: details });
+    }
+    /**
+     * Creates an expired authorization error
+     */
+    static authorizationExpired(provider, details) {
+        return new OAuthError(OAuthErrorType.AUTHORIZATION_EXPIRED, provider, `Authorization expired for ${provider}`, { technicalDetails: details });
+    }
+    /**
+     * Creates a network error with retry capability
+     */
+    static networkError(provider, originalError, details) {
+        return new OAuthError(OAuthErrorType.NETWORK_ERROR, provider, `Network error connecting to ${provider}`, {
+            originalError,
+            technicalDetails: details,
+            retryAfterMs: 1000, // Retry after 1 second
+        });
+    }
+    /**
+     * Creates a rate limited error with specific retry delay
+     */
+    static rateLimited(provider, retryAfterSeconds = 60, details) {
+        return new OAuthError(OAuthErrorType.RATE_LIMITED, provider, `Rate limited by ${provider}`, {
+            technicalDetails: details,
+            retryAfterMs: retryAfterSeconds * 1000,
+        });
+    }
+    /**
+     * Creates a storage error
+     */
+    static storageError(provider, originalError, details) {
+        return new OAuthError(OAuthErrorType.STORAGE_ERROR, provider, `Storage error for ${provider}`, { originalError, technicalDetails: details });
+    }
+    /**
+     * Creates a corrupted data error
+     */
+    static corruptedData(provider, details) {
+        return new OAuthError(OAuthErrorType.CORRUPTED_DATA, provider, `Corrupted data for ${provider}`, { technicalDetails: details });
+    }
+    /**
+     * Creates an error from an unknown error, attempting classification
+     */
+    static fromUnknown(provider, error, context) {
+        let originalError = null;
+        let message = 'Unknown error';
+        let type = OAuthErrorType.UNKNOWN;
+        if (error instanceof Error) {
+            originalError = error;
+            message = error.message;
+            // Attempt to classify based on error message or type
+            const errorWithCode = error;
+            if (error.message.toLowerCase().includes('network') ||
+                error.message.toLowerCase().includes('connection') ||
+                errorWithCode.code === 'ENOTFOUND' ||
+                errorWithCode.code === 'ECONNREFUSED') {
+                type = OAuthErrorType.NETWORK_ERROR;
+            }
+            else if (error.message.toLowerCase().includes('timeout')) {
+                type = OAuthErrorType.TIMEOUT;
+            }
+            else if (error.message.toLowerCase().includes('permission') ||
+                errorWithCode.code === 'EACCES' ||
+                errorWithCode.code === 'EPERM') {
+                type = OAuthErrorType.FILE_PERMISSIONS;
+            }
+            else if (error.message.toLowerCase().includes('unauthorized') ||
+                error.message.toLowerCase().includes('invalid_grant') ||
+                error.message.toLowerCase().includes('expired')) {
+                type = OAuthErrorType.AUTHORIZATION_EXPIRED;
+            }
+            else if (error.message.toLowerCase().includes('rate') ||
+                error.message.toLowerCase().includes('too many')) {
+                type = OAuthErrorType.RATE_LIMITED;
+            }
+        }
+        else if (typeof error === 'string') {
+            message = error;
+        }
+        else {
+            message = String(error);
+        }
+        return new OAuthError(type, provider, context ? `${context}: ${message}` : message, {
+            originalError: originalError ?? undefined,
+            technicalDetails: { context, originalErrorType: typeof error },
+        });
+    }
+}
+/**
+ * Retry handler with exponential backoff and jitter
+ */
+export class RetryHandler {
+    config;
+    constructor(config = DEFAULT_RETRY_CONFIG) {
+        this.config = config;
+    }
+    /**
+     * Executes operation with retry logic for transient errors
+     */
+    async executeWithRetry(operation, provider, context) {
+        let lastError = null;
+        for (let attempt = 1; attempt <= this.config.maxAttempts; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                // Convert to OAuthError if not already
+                const oauthError = error instanceof OAuthError
+                    ? error
+                    : OAuthErrorFactory.fromUnknown(provider, error, context);
+                lastError = oauthError;
+                // Don't retry non-transient errors
+                if (!oauthError.isRetryable) {
+                    throw oauthError;
+                }
+                // Don't retry on the last attempt
+                if (attempt >= this.config.maxAttempts) {
+                    break;
+                }
+                // Calculate delay with exponential backoff and jitter
+                let delay = oauthError.retryAfterMs ??
+                    Math.min(this.config.baseDelayMs *
+                        Math.pow(this.config.backoffMultiplier, attempt - 1), this.config.maxDelayMs);
+                if (this.config.jitter) {
+                    delay = delay * (0.5 + Math.random() * 0.5); // 50-100% of calculated delay
+                }
+                console.debug(`${provider} operation failed (attempt ${attempt}/${this.config.maxAttempts}), retrying in ${delay}ms...`);
+                await this.sleep(delay);
+            }
+        }
+        // All retries exhausted
+        throw (lastError ??
+            OAuthErrorFactory.fromUnknown(provider, new Error('Max retries exceeded'), context));
+    }
+    /**
+     * Sleep utility
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Graceful error handler for OAuth operations
+ */
+export class GracefulErrorHandler {
+    retryHandler;
+    constructor(retryHandler = new RetryHandler()) {
+        this.retryHandler = retryHandler;
+    }
+    /**
+     * Handles errors gracefully, providing fallback behavior when possible
+     */
+    async handleGracefully(operation, fallback, provider, context) {
+        try {
+            return await this.retryHandler.executeWithRetry(operation, provider, context);
+        }
+        catch (error) {
+            const oauthError = error instanceof OAuthError
+                ? error
+                : OAuthErrorFactory.fromUnknown(provider, error, context);
+            // Log the error for debugging
+            console.debug('OAuth operation failed gracefully:', oauthError.toLogEntry());
+            // Critical errors should not be handled gracefully
+            if (oauthError.category === OAuthErrorCategory.CRITICAL) {
+                throw oauthError;
+            }
+            // Return fallback for non-critical errors
+            if (typeof fallback === 'function') {
+                return fallback();
+            }
+            return fallback;
+        }
+    }
+    /**
+     * Wraps a method to handle errors gracefully with logging
+     */
+    wrapMethod(method, provider, methodName, fallback) {
+        return async (...args) => {
+            try {
+                return await this.retryHandler.executeWithRetry(() => method(...args), provider, methodName);
+            }
+            catch (error) {
+                const oauthError = error instanceof OAuthError
+                    ? error
+                    : OAuthErrorFactory.fromUnknown(provider, error, methodName);
+                // Always show user-friendly error message for user-actionable errors
+                if (oauthError.category === OAuthErrorCategory.USER_ACTION_REQUIRED) {
+                    console.error(oauthError.userMessage);
+                    if (oauthError.actionRequired) {
+                        console.error(`Action required: ${oauthError.actionRequired}`);
+                    }
+                }
+                // Log technical details for debugging
+                console.debug(`${provider}.${methodName} failed:`, oauthError.toLogEntry());
+                // Use fallback if provided and error is not critical
+                if (fallback !== undefined &&
+                    oauthError.category !== OAuthErrorCategory.CRITICAL) {
+                    if (typeof fallback === 'function') {
+                        return fallback(...args);
+                    }
+                    return fallback;
+                }
+                throw oauthError;
+            }
+        };
+    }
+}
+//# sourceMappingURL=oauth-errors.js.map

package/dist/src/oauth-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-errors.js","sourceRoot":"","sources":["../../src/oauth-errors.ts"],"names":[],"mappings":"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"}

package/dist/src/precedence.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Authentication precedence utility for providers
+ *
+ * Implements the authentication precedence chain:
+ * 1. Provider-specific auth-key/keyfile (from getProviderSettings)
+ * 2. Constructor API key
+ * 3. Global auth-key/keyfile (from settings when activeProvider matches)
+ * 4. Environment variables
+ * 5. OAuth (if enabled)
+ *
+ * @plan PLAN-20260608-ISSUE1586.P09
+ * @requirement REQ-AUTH-001.1, REQ-API-001.4
+ */
+import type { ISettingsService } from './interfaces/settings-service.js';
+import type { IProviderRuntimeContext } from './interfaces/runtime-context.js';
+import type { IDebugLogger } from './interfaces/debug-logger.js';
+export interface AuthPrecedenceConfig {
+    apiKey?: string;
+    envKeyNames?: string[];
+    isOAuthEnabled?: boolean;
+    supportsOAuth?: boolean;
+    oauthProvider?: string;
+    providerId?: string;
+}
+import { type OAuthToken } from './types.js';
+export interface OAuthTokenRequestMetadata {
+    runtimeAuthScopeId?: string;
+    providerId?: string;
+    profileId?: string;
+    cliScope?: Record<string, unknown>;
+    runtimeMetadata?: Record<string, unknown>;
+}
+export interface OAuthManager {
+    getToken(provider: string, metadata?: OAuthTokenRequestMetadata): Promise<string | null>;
+    isAuthenticated(provider: string): Promise<boolean>;
+    getOAuthToken?(provider: string, metadata?: OAuthTokenRequestMetadata): Promise<OAuthToken | null>;
+    /**
+     * Force refresh a token when it is known to be revoked.
+     * @fix issue1861 - Token revocation handling
+     */
+    forceRefreshToken?(provider: string, failedAccessToken: string): Promise<OAuthToken | null>;
+}
+/**
+ * @plan PLAN-20251018-STATELESSPROVIDER2.P18
+ * @requirement REQ-SP2-004
+ * Runtime-scoped credential bookkeeping keyed by runtime, provider, and profile identifiers.
+ */
+export interface RuntimeScopedAuthEntry {
+    key: string;
+    providerId: string;
+    profileId: string;
+    runtimeAuthScopeId: string;
+    token: string;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt?: number;
+    stale: boolean;
+    cancellationHook?: () => void | Promise<void>;
+}
+export interface RuntimeAuthScopeCacheEntrySummary {
+    key: string;
+    providerId: string;
+    profileId: string;
+    runtimeAuthScopeId: string;
+    preview: string;
+    createdAt: number;
+    expiresAt?: number;
+    stale: boolean;
+    reason?: string;
+}
+interface RuntimeAuthScopeMetadataRecord {
+    runtimeAuthScopeId: string;
+    cacheEntries: RuntimeAuthScopeCacheEntrySummary[];
+    cancellationHooks: Array<() => void | Promise<void>>;
+    revokedTokens: RuntimeAuthScopeCacheEntrySummary[];
+    metrics: {
+        hits: number;
+        misses: number;
+        lastUpdated: number;
+    };
+}
+export interface RuntimeScopedState {
+    runtimeAuthScopeId: string;
+    entries: Map<string, RuntimeScopedAuthEntry>;
+    metadata: RuntimeAuthScopeMetadataRecord;
+    settingsService?: ISettingsService;
+    settingsSubscriptions: Array<() => void>;
+}
+export declare const runtimeScopedStates: Map<string, RuntimeScopedState>;
+export declare function resolveProfileId(settingsService: ISettingsService): string | null;
+export declare function buildCacheKey(runtimeId: string, providerId: string, profileId: string): string;
+export declare function ensureRuntimeState(context: IProviderRuntimeContext, logger?: IDebugLogger): RuntimeScopedState;
+export declare function recordCacheHit(state: RuntimeScopedState): void;
+export declare function recordCacheMiss(state: RuntimeScopedState): void;
+export declare function getValidCachedEntry(state: RuntimeScopedState, providerId: string, profileId: string): RuntimeScopedAuthEntry | null;
+export declare function registerSettingsSubscriptions(state: RuntimeScopedState, settingsService: ISettingsService, providerId: string, logger?: IDebugLogger): void;
+export declare function invalidateMatchingEntries(state: RuntimeScopedState, predicate: (entry: RuntimeScopedAuthEntry) => boolean, reason: string): RuntimeAuthScopeCacheEntrySummary[];
+export declare function storeRuntimeScopedToken(state: RuntimeScopedState, providerId: string, profileId: string, token: string, oauthToken?: OAuthToken | null): void;
+export declare function invalidateEntry(state: RuntimeScopedState, cacheKey: string, reason: string): RuntimeAuthScopeCacheEntrySummary;
+export interface RuntimeAuthScopeFlushResult {
+    runtimeId: string;
+    revokedTokens: RuntimeAuthScopeCacheEntrySummary[];
+}
+/**
+ * Flush scoped credentials for a runtime and return revocation metadata.
+ * @plan PLAN-20251018-STATELESSPROVIDER2.P18, PLAN-20260608-ISSUE1586.P09
+ * @requirement REQ-SP2-004, REQ-API-001.4
+ */
+export declare function flushRuntimeAuthScope(runtimeId: string): RuntimeAuthScopeFlushResult;
+export { AuthPrecedenceResolver } from './auth-precedence-resolver.js';