matrix-quotes-bot/node_modules/matrix-js-sdk/lib/autodiscovery.d.ts

import { SigningKey } from "oidc-client-ts";
import { IClientWellKnown, IWellKnownConfig, IDelegatedAuthConfig } from "./client";
import { ValidatedIssuerConfig, ValidatedIssuerMetadata } from "./oidc/validate";
export declare enum AutoDiscoveryAction {
    SUCCESS = "SUCCESS",
    IGNORE = "IGNORE",
    PROMPT = "PROMPT",
    FAIL_PROMPT = "FAIL_PROMPT",
    FAIL_ERROR = "FAIL_ERROR"
}
declare enum AutoDiscoveryError {
    Invalid = "Invalid homeserver discovery response",
    GenericFailure = "Failed to get autodiscovery configuration from server",
    InvalidHsBaseUrl = "Invalid base_url for m.homeserver",
    InvalidHomeserver = "Homeserver URL does not appear to be a valid Matrix homeserver",
    InvalidIsBaseUrl = "Invalid base_url for m.identity_server",
    InvalidIdentityServer = "Identity server URL does not appear to be a valid identity server",
    InvalidIs = "Invalid identity server discovery response",
    MissingWellknown = "No .well-known JSON file found",
    InvalidJson = "Invalid JSON"
}
interface AutoDiscoveryState {
    state: AutoDiscoveryAction;
    error?: IWellKnownConfig["error"] | null;
}
interface WellKnownConfig extends Omit<IWellKnownConfig, "error">, AutoDiscoveryState {
}
/**
 * @deprecated in favour of OidcClientConfig
 */
interface DelegatedAuthConfig extends IDelegatedAuthConfig, ValidatedIssuerConfig, AutoDiscoveryState {
}
/**
 * @experimental
 */
export interface OidcClientConfig extends IDelegatedAuthConfig, ValidatedIssuerConfig {
    metadata: ValidatedIssuerMetadata;
    signingKeys?: SigningKey[];
}
export interface ClientConfig extends Omit<IClientWellKnown, "m.homeserver" | "m.identity_server"> {
    "m.homeserver": WellKnownConfig;
    "m.identity_server": WellKnownConfig;
    /**
     * @experimental
     */
    "m.authentication"?: (OidcClientConfig & AutoDiscoveryState) | AutoDiscoveryState;
}
/**
 * Utilities for automatically discovery resources, such as homeservers
 * for users to log in to.
 */
export declare class AutoDiscovery {
    static readonly ERROR_INVALID = AutoDiscoveryError.Invalid;
    static readonly ERROR_GENERIC_FAILURE = AutoDiscoveryError.GenericFailure;
    static readonly ERROR_INVALID_HS_BASE_URL = AutoDiscoveryError.InvalidHsBaseUrl;
    static readonly ERROR_INVALID_HOMESERVER = AutoDiscoveryError.InvalidHomeserver;
    static readonly ERROR_INVALID_IS_BASE_URL = AutoDiscoveryError.InvalidIsBaseUrl;
    static readonly ERROR_INVALID_IDENTITY_SERVER = AutoDiscoveryError.InvalidIdentityServer;
    static readonly ERROR_INVALID_IS = AutoDiscoveryError.InvalidIs;
    static readonly ERROR_MISSING_WELLKNOWN = AutoDiscoveryError.MissingWellknown;
    static readonly ERROR_INVALID_JSON = AutoDiscoveryError.InvalidJson;
    static readonly ALL_ERRORS: string[];
    /**
     * The auto discovery failed. The client is expected to communicate
     * the error to the user and refuse logging in.
     */
    static readonly FAIL_ERROR = AutoDiscoveryAction.FAIL_ERROR;
    /**
     * The auto discovery failed, however the client may still recover
     * from the problem. The client is recommended to that the same
     * action it would for PROMPT while also warning the user about
     * what went wrong. The client may also treat this the same as
     * a FAIL_ERROR state.
     */
    static readonly FAIL_PROMPT = AutoDiscoveryAction.FAIL_PROMPT;
    /**
     * The auto discovery didn't fail but did not find anything of
     * interest. The client is expected to prompt the user for more
     * information, or fail if it prefers.
     */
    static readonly PROMPT = AutoDiscoveryAction.PROMPT;
    /**
     * The auto discovery was successful.
     */
    static readonly SUCCESS = AutoDiscoveryAction.SUCCESS;
    /**
     * Validates and verifies client configuration information for purposes
     * of logging in. Such information includes the homeserver URL
     * and identity server URL the client would want. Additional details
     * may also be included, and will be transparently brought into the
     * response object unaltered.
     * @param wellknown - The configuration object itself, as returned
     * by the .well-known auto-discovery endpoint.
     * @returns Promise which resolves to the verified
     * configuration, which may include error states. Rejects on unexpected
     * failure, not when verification fails.
     */
    static fromDiscoveryConfig(wellknown: IClientWellKnown): Promise<ClientConfig>;
    /**
     * Validate delegated auth configuration
     * @deprecated use discoverAndValidateAuthenticationConfig
     * - m.authentication config is present and valid
     * - delegated auth issuer openid-configuration is reachable
     * - delegated auth issuer openid-configuration is configured correctly for us
     * When successful, DelegatedAuthConfig will be returned with endpoints used for delegated auth
     * Any errors are caught, and AutoDiscoveryState returned with error
     * @param wellKnown - configuration object as returned
     * by the .well-known auto-discovery endpoint
     * @returns Config or failure result
     */
    static validateDiscoveryAuthenticationConfig(wellKnown: IClientWellKnown): Promise<DelegatedAuthConfig | AutoDiscoveryState>;
    /**
     * Validate delegated auth configuration
     * - m.authentication config is present and valid
     * - delegated auth issuer openid-configuration is reachable
     * - delegated auth issuer openid-configuration is configured correctly for us
     * When successful, validated authentication metadata and optionally signing keys will be returned
     * Any errors are caught, and AutoDiscoveryState returned with error
     * @param wellKnown - configuration object as returned
     * by the .well-known auto-discovery endpoint
     * @returns Config or failure result
     */
    static discoverAndValidateAuthenticationConfig(wellKnown: IClientWellKnown): Promise<(OidcClientConfig & AutoDiscoveryState) | AutoDiscoveryState>;
    /**
     * Attempts to automatically discover client configuration information
     * prior to logging in. Such information includes the homeserver URL
     * and identity server URL the client would want. Additional details
     * may also be discovered, and will be transparently included in the
     * response object unaltered.
     * @param domain - The homeserver domain to perform discovery
     * on. For example, "matrix.org".
     * @returns Promise which resolves to the discovered
     * configuration, which may include error states. Rejects on unexpected
     * failure, not when discovery fails.
     */
    static findClientConfig(domain: string): Promise<ClientConfig>;
    /**
     * Gets the raw discovery client configuration for the given domain name.
     * Should only be used if there's no validation to be done on the resulting
     * object, otherwise use findClientConfig().
     * @param domain - The domain to get the client config for.
     * @returns Promise which resolves to the domain's client config. Can
     * be an empty object.
     */
    static getRawClientConfig(domain?: string): Promise<IClientWellKnown>;
    /**
     * Sanitizes a given URL to ensure it is either an HTTP or HTTP URL and
     * is suitable for the requirements laid out by .well-known auto discovery.
     * If valid, the URL will also be stripped of any trailing slashes.
     * @param url - The potentially invalid URL to sanitize.
     * @returns The sanitized URL or a falsey value if the URL is invalid.
     * @internal
     */
    private static sanitizeWellKnownUrl;
    private static fetch;
    private static fetchFn?;
    static setFetchFn(fetchFn: typeof global.fetch): void;
    /**
     * Fetches a JSON object from a given URL, as expected by all .well-known
     * related lookups. If the server gives a 404 then the `action` will be
     * IGNORE. If the server returns something that isn't JSON, the `action`
     * will be FAIL_PROMPT. For any other failure the `action` will be FAIL_PROMPT.
     *
     * The returned object will be a result of the call in object form with
     * the following properties:
     *   raw: The JSON object returned by the server.
     *   action: One of SUCCESS, IGNORE, or FAIL_PROMPT.
     *   reason: Relatively human-readable description of what went wrong.
     *   error: The actual Error, if one exists.
     * @param url - The URL to fetch a JSON object from.
     * @returns Promise which resolves to the returned state.
     * @internal
     */
    private static fetchWellKnownObject;
}
export {};
//# sourceMappingURL=autodiscovery.d.ts.map