passport-steam-openid/dist/strategy.d.ts

Passport strategy for authenticating with steam openid without the use of 3rd party openid packages.

/// <reference types="node" />
import { ParsedUrlQuery } from 'querystring';
import { Strategy } from 'passport';
import { SteamOpenIdUserProfile, SteamOpenIdUser, SteamOpenIdQuery, SteamOpenIdStrategyOptionsWithProfile, SteamOpenIdStrategyOptionsWithoutProfile, VerifyCallback, IAxiosLikeHttpClient } from './type';
/**
 * Strategy that authenticates you via steam openid without the use of any external openid libraries,
 * which can and are source of many vulnerabilities.
 *
 * Functionality should be similar to `passport-steam`.
 *
 * @class SteamOpenIdStrategy
 */
export declare class SteamOpenIdStrategy<TOptions extends SteamOpenIdStrategyOptionsWithProfile | SteamOpenIdStrategyOptionsWithoutProfile, TUser extends SteamOpenIdUser | SteamOpenIdUserProfile = TOptions extends SteamOpenIdStrategyOptionsWithProfile ? SteamOpenIdUserProfile : SteamOpenIdUser> extends Strategy {
    /**
     * Axios instance used for validating the request and fetching profile.
     */
    protected readonly http: IAxiosLikeHttpClient;
    /**
     * Where in your app, you want to return to from steam.
     *
     * This route has to have passport authentication middleware.
     */
    protected readonly returnURL: string;
    /**
     * Steam Api key used for fetching profile.
     */
    protected readonly apiKey?: string;
    /**
     * Signalizes, if profile should be fetched.
     */
    protected readonly profile: boolean;
    /**
     * optional callback, called when user is successfully authenticated
     */
    protected verify?: VerifyCallback<TUser>;
    /**
     * Optional setting for validating nonce time delay,
     * in seconds.
     *
     * Measures time between nonce creation date and verification.
     */
    protected maxNonceTimeDelay: number | undefined;
    /**
     * @constructor
     *
     * @param options.returnURL where steam redirects after parameters are passed
     * @param options.profile if set, we will fetch user's profile from steam api
     * @param options.apiKey api key to fetch user profile, not used if profile is false
     * @param options.maxNonceTimeDelay optional setting for validating nonce time delay,
     *  this is just an extra security measure, it is not required nor recommended, but
     *  might be extra layer of security you want to have.
     * @param verify optional callback, called when user is successfully authenticated
     */
    constructor(options: TOptions, verify?: VerifyCallback<TUser>);
    /**
     * Passport handle for authentication. We handle the query, passport does rest.
     *
     * @param req Base IncommingMessage request enhanced with parsed querystring.
     */
    authenticate(req: any): Promise<void>;
    /**
     * Handles validation request.
     *
     * Can be used in a middleware, if you don't like passport.
     *
     * @param req Base IncommingMessage request enhanced with parsed querystring.
     * @returns
     * @throws {SteamOpenIdError} User related problem, such as:
     *  - open.mode was not correct
     *  - query did not was pass validation
     *  - steam rejected this query
     *  - steamid is invalid
     * @throws {Error} Non-recoverable errors, such as query object missing.
     */
    handleRequest(req: any): Promise<TUser>;
    /**
     * Check if nonce date has expired against current delay setting,
     * if no setting was set, then it is considered as not expired.
     *
     * @param nonceDate date when nonce was created
     * @returns true, if nonce has expired and error should be thrown
     */
    protected hasNonceExpired(query: SteamOpenIdQuery): boolean;
    /**
     * Checks if error is retryable,
     * meaning user gets redirected to steam openid page.
     *
     * @param err from catch clause
     * @returns true, if error should be retried
     * @returns false, if error is not retriable
     *  and should be handled by the app.
     */
    protected isRetryableError(err: unknown): boolean;
    /**
     * Retrieves query parameter from req object and checks if it is an object.
     *
     * @param req Base IncommingMessage request enhanced with parsed querystring.
     * @returns query from said request
     * @throws Error if query cannot be found, non-recoverable error.
     */
    protected getQuery(req: any): ParsedUrlQuery;
    /**
     * Checks if `mode` field from query is correct and thus authentication can begin
     *
     * @param query original query user submitted
     * @returns true, if mode is correct, equal to `id_res`
     * @returns false, if mode is incorrect
     */
    protected hasAuthQuery(query: ParsedUrlQuery): boolean;
    /**
     * Builds a redirect url for user that is about to authenticate
     *
     * @returns redirect url built with proper parameters
     */
    buildRedirectUrl(): string;
    /**
     * Validates user submitted query, if it contains correct parameters.
     * No excess parameters can be used.
     *
     * @param query original query user submitted
     * @returns true, query contains correct parameters
     * @returns false, query contains incorrect parameters
     */
    protected isQueryValid(query: ParsedUrlQuery): query is SteamOpenIdQuery;
    /**
     * Checks if identity starts with correct link.
     *
     * @param identity from querystring
     * @returns true, if identity is a string and starts with correct endpoint
     * @return false, if above criteria was violated
     */
    protected isValidIdentity(identity: string | unknown): boolean;
    /**
     * Query trusted steam endpoint to validate supplied query.
     *
     * @param query original query user submitted
     * @returns true, if positive response was received
     * @returns false, if request failed, status is incorrect or data signals invalid
     */
    protected validateAgainstSteam(query: SteamOpenIdQuery): Promise<boolean>;
    /**
     * Clones query from authentication request, changes mode and stringifies to form data.
     * @param query original query user submitted
     * @returns stringified form data with changed mode
     */
    protected getOpenIdValidationRequestBody(query: SteamOpenIdQuery): string;
    /**
     * Validates response from steam to see if query is correct.
     *
     * @param response response received from steama
     * @returns true, if data was in correct format and signals valid query
     * @return false, if data was corrupted or invalid query was signaled
     */
    protected isSteamResponseValid(response: any): boolean;
    /**
     * Parses steamId from `claimed_id` field, which is what openid 2.0 uses.
     *
     * @param query original query user submitted
     * @returns parsed steamId
     */
    protected getSteamId(query: SteamOpenIdQuery): string;
    /**
     * Abstract method for getting user that has been authenticated.
     * You can implement fetching user from steamid and thus validating even more,
     * or if you are satisified with just steamId, you can return it as an object
     * and continue without need of an steam api key.
     *
     * @param steamId steamId parsed from `claimed_id`
     * @return generic that was chosen by child class
     */
    protected getUser(steamId: string): Promise<TUser>;
    /**
     * Fetches profile data for authenticated user.
     * Validates the steamId even more.
     *
     * @param steamId parsed steamId from `claimed_id`
     * @returns profile belonging to said steamId
     *
     * @throws {Error} if malformed response was received
     * @throws {AxiosError} if status was not 200
     * @throws {SteamOpenIdError} if profile was not found
     */
    protected fetchPlayerSummary(steamId: string): Promise<SteamOpenIdUserProfile>;
}
//# sourceMappingURL=strategy.d.ts.map