oauth2-mock-server/dist/types/index.d.ts

OAuth 2 mock server

import { RequestListener, IncomingMessage } from 'node:http';
import { AddressInfo } from 'node:net';
import { ServerOptions } from 'node:https';
import { JWK as JWK$1 } from 'jose';
import { EventEmitter } from 'node:events';

interface JWKWithKid extends JWK$1 {
    kid: string;
    alg: string;
    [propName: string]: unknown;
}

/**
 * Copyright (c) AXA Assistance France
 *
 * Licensed under the AXA Assistance France License (the "License"); you
 * may not use this file except in compliance with the License.
 * A copy of the License can be found in the LICENSE.md file distributed
 * together with this file.
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

declare const supportedPkceAlgorithms: readonly ["plain", "S256"];

interface TokenRequest {
    scope?: string;
    grant_type: string;
    username?: unknown;
    client_id?: unknown;
    code?: string;
    aud?: string[] | string;
    code_verifier?: string;
}
interface Options {
    host?: string;
    port: number;
    cert?: string;
    key?: string;
    keys: Record<string, unknown>[];
    saveJWK: boolean;
}
type HttpServerOptions = Pick<ServerOptions, 'key'> & Pick<ServerOptions, 'cert'>;
interface MutableRedirectUri {
    url: URL;
}
interface MutableToken {
    header: Header;
    payload: Payload;
}
interface Header {
    kid: string;
    [key: string]: unknown;
}
interface Payload {
    iss: string;
    iat: number;
    exp: number;
    nbf: number;
    [key: string]: unknown;
}
interface StatusCodeMutableResponse {
    statusCode: number;
}
interface MutableResponse extends StatusCodeMutableResponse {
    body: Record<string, unknown> | '';
}
type ScopesOrTransform = string | string[] | JwtTransform;
type JwtTransform = (header: Header, payload: Payload) => void;
declare enum Events {
    BeforeTokenSigning = "beforeTokenSigning",
    BeforeResponse = "beforeResponse",
    BeforeUserinfo = "beforeUserinfo",
    BeforeRevoke = "beforeRevoke",
    BeforeAuthorizeRedirect = "beforeAuthorizeRedirect",
    BeforePostLogoutRedirect = "beforePostLogoutRedirect",
    BeforeIntrospect = "beforeIntrospect"
}
interface TokenBuildOptions {
    /**
     * The 'kid' of the key that will be used to sign the JWT.
     * If omitted, the next key in the round - robin will be used.
     */
    kid?: string | undefined;
    /**
     * A scope, array of scopes, or JWT transformation callback.
     */
    scopesOrTransform?: ScopesOrTransform | undefined;
    /**
     * Time in seconds before the JWT to expire. Default: 3600 seconds.
     */
    expiresIn?: number | undefined;
}
interface JWK extends JWKWithKid {
    alg: string;
}
interface OAuth2Endpoints {
    wellKnownDocument: string;
    token: string;
    jwks: string;
    authorize: string;
    userinfo: string;
    revoke: string;
    endSession: string;
    introspect: string;
}
type OAuth2EndpointsInput = Partial<OAuth2Endpoints>;
interface OAuth2Options {
    endpoints?: OAuth2EndpointsInput;
}
type PKCEAlgorithm = (typeof supportedPkceAlgorithms)[number];
interface CodeChallenge {
    challenge: string;
    method: PKCEAlgorithm;
}

/**
 * Copyright (c) AXA Assistance France
 *
 * Licensed under the AXA Assistance France License (the "License"); you
 * may not use this file except in compliance with the License.
 * A copy of the License can be found in the LICENSE.md file distributed
 * together with this file.
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * HTTP Server library
 * @module lib/http-server
 */

/**
 * Provides a restartable wrapper for http.CreateServer().
 */
declare class HttpServer {
    #private;
    /**
     * Creates a new instance of HttpServer.
     * @param requestListener The function that will handle the server's requests.
     * @param options Optional HttpServerOptions to start the server with https.
     */
    constructor(requestListener: RequestListener, options?: HttpServerOptions);
    /**
     * Returns a value indicating whether or not the server is listening for connections.
     * @returns A boolean value indicating whether the server is listening.
     */
    get listening(): boolean;
    /**
     * Returns the bound address, family name and port where the server is listening,
     * or null if the server has not been started.
     * @returns The server bound address information.
     */
    address(): AddressInfo;
    /**
     * Starts the server.
     * @param port Port number. If omitted, it will be assigned by the operating system.
     * @param host Host name.
     * @returns A promise that resolves when the server has been started.
     */
    start(port?: number, host?: string): Promise<void>;
    /**
     * Stops the server.
     * @returns Resolves when the server has been stopped.
     */
    stop(): Promise<void>;
    protected buildIssuerUrl(host: string | undefined, port: number): string;
}

/**
 * Copyright (c) AXA Assistance France
 *
 * Licensed under the AXA Assistance France License (the "License"); you
 * may not use this file except in compliance with the License.
 * A copy of the License can be found in the LICENSE.md file distributed
 * together with this file.
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Simple JWK store
 */
declare class JWKStore {
    #private;
    /**
     * Creates a new instance of the keystore.
     */
    constructor();
    /**
     * Generates a new random key and adds it into this keystore.
     * @param alg The selected algorithm.
     * @param opts The options.
     * @param opts.kid The key identifier to use.
     * @param opts.crv The OKP "crv" to be used for "EdDSA" algorithm.
     * @returns The promise for the generated key.
     */
    generate(alg: string, opts?: {
        kid?: string;
        crv?: string;
    }): Promise<JWK>;
    /**
     * Adds a JWK key to this keystore.
     * @param maybeJwk The JWK key to add.
     * @returns The promise for the added key.
     */
    add(maybeJwk: Record<string, unknown>): Promise<JWK>;
    /**
     * Gets a key from the keystore in a round-robin fashion.
     * If a 'kid' is provided, only keys that match will be taken into account.
     * @param kid The optional key identifier to match keys against.
     * @returns The retrieved key.
     */
    get(kid?: string): JWK | undefined;
    /**
     * Generates a JSON representation of this keystore, which conforms
     * to a JWK Set from {I-D.ietf-jose-json-web-key}.
     * @param [includePrivateFields] `true` if the private fields
     *        of stored keys are to be included.
     * @returns The JSON representation of this keystore.
     */
    toJSON(includePrivateFields?: boolean): JWK[];
}

/**
 * Copyright (c) AXA Assistance France
 *
 * Licensed under the AXA Assistance France License (the "License"); you
 * may not use this file except in compliance with the License.
 * A copy of the License can be found in the LICENSE.md file distributed
 * together with this file.
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * OAuth2 Issuer library
 * @module lib/oauth2-issuer
 */

/**
 * Represents an OAuth 2 issuer.
 */
declare class OAuth2Issuer extends EventEmitter {
    #private;
    /**
     * Sets or returns the issuer URL.
     */
    url: string | undefined;
    /**
     * Creates a new instance of HttpServer.
     */
    constructor();
    /**
     * Returns the key store.
     * @returns The key store.
     */
    get keys(): JWKStore;
    /**
     * Builds a JWT.
     * @param opts JWT token building overrides
     * @returns The produced JWT.
     * @fires OAuth2Issuer#beforeSigning
     */
    buildToken(opts?: TokenBuildOptions): Promise<string>;
}

/**
 * Copyright (c) AXA Assistance France
 *
 * Licensed under the AXA Assistance France License (the "License"); you
 * may not use this file except in compliance with the License.
 * A copy of the License can be found in the LICENSE.md file distributed
 * together with this file.
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * OAuth2 Service library
 * @module lib/oauth2-service
 */

/**
 * Provides a request handler for an OAuth 2 server.
 */
declare class OAuth2Service extends EventEmitter {
    #private;
    constructor(oauth2Issuer: OAuth2Issuer, endpoints?: OAuth2EndpointsInput);
    /**
     * Returns the OAuth2Issuer instance bound to this service.
     * @returns The OAuth2Issuer instance.
     */
    get issuer(): OAuth2Issuer;
    /**
     * Builds a JWT with a key in the keystore. The key will be selected in a round-robin fashion.
     * @param req The incoming HTTP request.
     * @param expiresIn Time in seconds for the JWT to expire. Default: 3600 seconds.
     * @param scopesOrTransform A scope, array of scopes,
     *     or JWT transformation callback.
     * @returns The produced JWT.
     * @fires OAuth2Service#beforeTokenSigning
     */
    buildToken(req: IncomingMessage, expiresIn: number, scopesOrTransform: ScopesOrTransform | undefined): Promise<string>;
    /**
     * Returns a request handler to be used as a callback for http.createServer().
     * @returns The request handler.
     */
    get requestHandler(): RequestListener;
    private buildRequestHandler;
    private openidConfigurationHandler;
    private jwksHandler;
    private tokenHandler;
    private authorizeHandler;
    private userInfoHandler;
    private revokeHandler;
    private endSessionHandler;
    private introspectHandler;
}

/**
 * Copyright (c) AXA Assistance France
 *
 * Licensed under the AXA Assistance France License (the "License"); you
 * may not use this file except in compliance with the License.
 * A copy of the License can be found in the LICENSE.md file distributed
 * together with this file.
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Represents an OAuth2 HTTP server.
 */
declare class OAuth2Server extends HttpServer {
    private _service;
    private _issuer;
    /**
     * Creates a new instance of OAuth2Server.
     * @param key Optional key file path for ssl
     * @param cert Optional cert file path for ssl
     * @param oauth2Options Optional additional settings
     * @returns A new instance of OAuth2Server.
     */
    constructor(key?: string, cert?: string, oauth2Options?: OAuth2Options);
    /**
     * Returns the OAuth2Issuer instance used by the server.
     * @returns The OAuth2Issuer instance.
     */
    get issuer(): OAuth2Issuer;
    /**
     * Returns the OAuth2Service instance used by the server.
     * @returns The OAuth2Service instance.
     */
    get service(): OAuth2Service;
    /**
     * Returns a value indicating whether or not the server is listening for connections.
     * @returns A boolean value indicating whether the server is listening.
     */
    get listening(): boolean;
    /**
     * Returns the bound address, family name and port where the server is listening,
     * or null if the server has not been started.
     * @returns The server bound address information.
     */
    address(): AddressInfo;
    /**
     * Starts the server.
     * @param port Port number. If omitted, it will be assigned by the operating system.
     * @param host Host name.
     * @returns A promise that resolves when the server has been started.
     */
    start(port?: number, host?: string): Promise<void>;
    /**
     * Stops the server.
     * @returns Resolves when the server has been stopped.
     */
    stop(): Promise<void>;
}

export { Events, HttpServer, JWKStore, OAuth2Issuer, OAuth2Server, OAuth2Service };
export type { CodeChallenge, Header, HttpServerOptions, JWK, JwtTransform, MutableRedirectUri, MutableResponse, MutableToken, OAuth2Endpoints, OAuth2EndpointsInput, OAuth2Options, Options, PKCEAlgorithm, Payload, ScopesOrTransform, StatusCodeMutableResponse, TokenBuildOptions, TokenRequest };