auth0 3.4.0 → 4.0.0-beta.1

package/dist/typings/auth/oauth.d.ts

@@ -0,0 +1,295 @@
+import { InitOverride, JSONApiResponse, VoidApiResponse } from '../lib/runtime.js';
+import { BaseAuthAPI, AuthenticationClientOptions } from './base-auth-api.js';
+import { IDTokenValidateOptions } from './id-token-validator.js';
+export interface TokenSet {
+    /**
+     * The access token.
+     */
+    access_token: string;
+    /**
+     * The refresh token, vavailable with the `offline_access` scope.
+     */
+    refresh_token?: string;
+    /**
+     * The user's ID Token.
+     */
+    id_token?: string;
+    /**
+     * The token type of the access token.
+     */
+    token_type: 'Bearer';
+    /**
+     * The duration in secs that that the access token is valid.
+     */
+    expires_in: number;
+}
+export interface GrantOptions {
+    idTokenValidateOptions?: Pick<IDTokenValidateOptions, 'organization'>;
+    initOverrides?: InitOverride;
+}
+export interface AuthorizationCodeGrantOptions {
+    idTokenValidateOptions?: IDTokenValidateOptions;
+    initOverrides?: InitOverride;
+}
+export interface ClientCredentials {
+    /**
+     * Specify this to override the parent class's `clientId`
+     */
+    client_id?: string;
+    /**
+     * Specify this to override the parent class's `clientSecret`
+     */
+    client_secret?: string;
+    /**
+     * Specify this to provide your own client assertion JWT rather than
+     * the class creating one for you from the `clientAssertionSigningKey`.
+     */
+    client_assertion?: string;
+    /**
+     * If you provide your own `client_assertion` you should also provide
+     * the `client_assertion_type`.
+     */
+    client_assertion_type?: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+}
+export interface AuthorizationCodeGrantRequest extends ClientCredentials {
+    /**
+     * The Authorization Code received from the initial `/authorize` call.
+     */
+    code: string;
+    /**
+     *	This is required only if it was set at the `/authorize` endpoint. The values must match.
+     */
+    redirect_uri?: string;
+}
+export interface AuthorizationCodeGrantWithPKCERequest extends AuthorizationCodeGrantRequest {
+    /**
+     * Cryptographically random key that was used to generate the code_challenge passed to `/authorize`.
+     */
+    code_verifier: string;
+}
+export interface ClientCredentialsGrantRequest extends ClientCredentials {
+    /**
+     * The unique identifier of the target API you want to access.
+     */
+    audience: string;
+}
+export interface PasswordGrantRequest extends ClientCredentials {
+    /**
+     * The unique identifier of the target API you want to access.
+     */
+    audience?: string;
+    /**
+     * Resource Owner's identifier, such as a username or email address.
+     */
+    username: string;
+    /**
+     * Resource Owner's secret.
+     */
+    password: string;
+    /**
+     * String value of the different scopes the application is asking for. Multiple scopes are separated with whitespace.
+     */
+    scope?: string;
+    /**
+     * String value of the realm the user belongs. Set this if you want to add realm support at this grant.
+     * For more information on what realms are refer to https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow#realm-support.
+     */
+    realm?: string;
+}
+export interface DeviceCodeGrantRequest {
+    /**
+     * Specify this to override the parent class's `clientId`
+     */
+    client_id?: string;
+    /**
+     * The device code previously returned from the `/oauth/device/code` endpoint.
+     */
+    device_code: string;
+}
+export interface RefreshTokenGrantRequest extends ClientCredentials {
+    /**
+     * The Refresh Token to use.
+     */
+    refresh_token: string;
+    /**
+     * A space-delimited list of requested scope permissions.
+     * If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes.
+     */
+    scope?: string;
+}
+export interface RevokeRefreshTokenRequest extends ClientCredentials {
+    /**
+     * The Refresh Token you want to revoke.
+     */
+    token: string;
+}
+export interface TokenExchangeGrantRequest {
+    /**
+     * Specify this to override the parent class's `clientId`
+     */
+    client_id?: string;
+    /**
+     * Externally-issued identity artifact, representing the user.
+     */
+    subject_token: string;
+    /**
+     * The unique identifier of the target API you want to access.
+     */
+    audience?: string;
+    /**
+     * String value of the different scopes the application is requesting.
+     * Multiple scopes are separated with whitespace.
+     */
+    scope?: string;
+    /**
+     * Optional element used for native iOS interactions for which profile updates can occur.
+     * Expected parameter value will be JSON in the form of: `{ name: { firstName: 'John', lastName: 'Smith }}`
+     */
+    user_profile: string;
+}
+/**
+ *  OAuth 2.0 flows.
+ */
+export declare class OAuth extends BaseAuthAPI {
+    private idTokenValidator;
+    constructor(options: AuthenticationClientOptions);
+    private validateIdToken;
+    /**
+     * Perform an OAuth 2.0 grant.
+     * (You should only need this if you can't find the grant you need in this library.)
+     */
+    grant(grantType: string, bodyParameters: Record<string, any>, { idTokenValidateOptions, initOverrides }?: GrantOptions): Promise<JSONApiResponse<TokenSet>>;
+    /**
+     * This is the flow that regular web apps use to access an API.
+     *
+     * Use this endpoint to exchange an Authorization Code for a Token.
+     *
+     * See: https://auth0.com/docs/api/authentication#authorization-code-flow44
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId',
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.oauth.authorizationCodeGrant({ code: 'mycode' });
+     * ```
+     */
+    authorizationCodeGrant(bodyParameters: AuthorizationCodeGrantRequest, options?: AuthorizationCodeGrantOptions): Promise<JSONApiResponse<TokenSet>>;
+    /**
+     * PKCE was originally designed to protect the authorization code flow in mobile apps,
+     * but its ability to prevent authorization code injection makes it useful for every type of OAuth client,
+     * even web apps that use client authentication.
+     *
+     * See: https://auth0.com/docs/api/authentication#authorization-code-flow-with-pkce45
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId',
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.oauth.authorizationCodeGrantWithPKCE({
+     *   code: 'mycode',
+     *   code_verifier: 'mycodeverifier'
+     * });
+     * ```
+     */
+    authorizationCodeGrantWithPKCE(bodyParameters: AuthorizationCodeGrantWithPKCERequest, options?: AuthorizationCodeGrantOptions): Promise<JSONApiResponse<TokenSet>>;
+    /**
+     * This is the OAuth 2.0 grant that server processes use to access an API.
+     *
+     * Use this endpoint to directly request an Access Token by using the Client's credentials
+     * (a Client ID and a Client Secret or a Client Assertion).
+     *
+     * See: https://auth0.com/docs/api/authentication#client-credentials-flow
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId',
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.oauth.clientCredentialsGrant({ audience: 'myaudience' });
+     * ```
+     */
+    clientCredentialsGrant(bodyParameters: ClientCredentialsGrantRequest, options?: {
+        initOverrides?: InitOverride;
+    }): Promise<JSONApiResponse<TokenSet>>;
+    /**
+     * This information is typically received from a highly trusted public client like a SPA*.
+     * (<strong>*Note:</string> For single-page applications and native/mobile apps, we recommend using web flows instead.)
+     *
+     * See: https://auth0.com/docs/api/authentication#resource-owner-password
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId'
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.oauth.clientCredentialsGrant({
+     *     username: 'myusername@example.com',
+     *     password: 'mypassword'
+     *   },
+     *   { headers: { 'auth0-forwarded-for': 'END.USER.IP.123' } }
+     * );
+     * ```
+     *
+     * Set the'auth0-forwarded-for' header to the end-user IP as a string value if you want
+     * brute-force protection to work in server-side scenarios.
+     *
+     * See https://auth0.com/docs/get-started/authentication-and-authorization-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection
+     *
+     */
+    passwordGrant(bodyParameters: PasswordGrantRequest, options?: GrantOptions): Promise<JSONApiResponse<TokenSet>>;
+    /**
+     * Use this endpoint to refresh an Access Token using the Refresh Token you got during authorization.
+     *
+     * See: https://auth0.com/docs/api/authentication#refresh-token
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId'
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.oauth.refreshTokenGrant({ refresh_token: 'myrefreshtoken' })
+     * ```
+     */
+    refreshTokenGrant(bodyParameters: RefreshTokenGrantRequest, options?: GrantOptions): Promise<JSONApiResponse<TokenSet>>;
+    /**
+     * Use this endpoint to invalidate a Refresh Token if it has been compromised.
+     *
+     * The behaviour of this endpoint depends on the state of the <a href="https://auth0.com/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens#refresh-tokens-and-grants">Refresh Token Revocation Deletes Grant</a> toggle.
+     * If this toggle is enabled, then each revocation request invalidates not only the specific token, but all other tokens based on the same authorization grant.
+     * This means that all Refresh Tokens that have been issued for the same user, application, and audience will be revoked.
+     * If this toggle is disabled, then only the refresh token is revoked, while the grant is left intact.
+     *
+     * See: https://auth0.com/docs/api/authentication#revoke-refresh-token
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId'
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.oauth.revokeRefreshToken({ token: 'myrefreshtoken' })
+     * ```
+     */
+    revokeRefreshToken(bodyParameters: RevokeRefreshTokenRequest, options?: {
+        initOverrides?: InitOverride;
+    }): Promise<VoidApiResponse>;
+}

package/dist/typings/auth/passwordless.d.ts

@@ -0,0 +1,165 @@
+import { InitOverride, JSONApiResponse, VoidApiResponse } from '../lib/runtime.js';
+import { BaseAuthAPI, AuthenticationClientOptions } from './base-auth-api.js';
+import { ClientCredentials, GrantOptions, TokenSet } from './oauth.js';
+export interface SendEmailLinkRequest {
+    /**
+     * The user's email address
+     */
+    email: string;
+    /**
+     * Use `link` to send a link or `code` to send a verification code.
+     * If omitted, a `link` will be sent.
+     */
+    send?: 'link';
+    /**
+     * Append or override the link parameters (like `scope`, `redirect_uri`, `protocol`, `response_type`),
+     * when you send a link using email.
+     */
+    authParams?: Record<string, unknown>;
+}
+export interface SendEmailCodeRequest {
+    /**
+     * The user's email address
+     */
+    email: string;
+    /**
+     * Use `link` to send a link or `code` to send a verification code.
+     * If omitted, a `link` will be sent.
+     */
+    send?: 'code';
+}
+export type SendEmailRequest = SendEmailLinkRequest | SendEmailCodeRequest;
+export interface SendSmsRequest {
+    /**
+     * The users phone number.
+     */
+    phone_number: string;
+}
+export interface LoginWithEmailRequest extends ClientCredentials {
+    /**
+     * The user's email address.
+     */
+    email: string;
+    /**
+     * The user's verification code.
+     */
+    code: string;
+    /**
+     * API Identifier of the API for which you want to get an Access Token.
+     */
+    audience?: string;
+    /**
+     * Use openid to get an ID Token, or openid profile email to also include user profile information in the ID Token.
+     */
+    scope?: string;
+}
+export interface LoginWithSMSRequest extends Omit<LoginWithEmailRequest, 'email'> {
+    /**
+     * The user's phone number.
+     */
+    phone_number: string;
+}
+/**
+ * Handles passwordless flows using Email and SMS.
+ */
+export declare class Passwordless extends BaseAuthAPI {
+    private oauth;
+    constructor(configuration: AuthenticationClientOptions);
+    /**
+     * Start passwordless flow sending an email.
+     *
+     * Given the user `email` address, it will send an email with:
+     *
+     * <ul>
+     *   <li>A link (default, `send:"link"`). You can then authenticate with this
+     *     user opening the link and he will be automatically logged in to the
+     *     application. Optionally, you can append/override parameters to the link
+     *     (like `scope`, `redirect_uri`, `protocol`, `response_type`, etc.) using
+     *     `authParams` object.
+     *   </li>
+     *   <li>
+     *     A verification code (`send:"code"`). You can then authenticate with
+     *     this user using the `/oauth/token` endpoint specifying `email` as
+     *     `username` and `code` as `password`.
+     *   </li>
+     * </ul>
+     *
+     * See: https://auth0.com/docs/api/authentication#get-code-or-link
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId',
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.passwordless.sendEmail({
+     *   email: '{EMAIL}',
+     *   send: 'link',
+     *   authParams: {} // Optional auth params.
+     * });
+     * ```
+     */
+    sendEmail(bodyParameters: SendEmailRequest, initOverrides?: InitOverride): Promise<VoidApiResponse>;
+    /**
+     * Start passwordless flow sending an SMS.
+     *
+     * Given the user `phone_number`, it will send a SMS message with a
+     * verification code. You can then authenticate with this user using the
+     * `/oauth/token` endpoint specifying `phone_number` as `username` and `code` as
+     * `password`:
+     *
+     * See: https://auth0.com/docs/api/authentication#get-code-or-link
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId',
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.passwordless.sendSMS({
+     *   phone_number: '{PHONE}'
+     * });
+     * ```
+     */
+    sendSMS(bodyParameters: SendSmsRequest, initOverrides?: InitOverride): Promise<VoidApiResponse>;
+    /**
+     * Once you have a verification code, use this endpoint to login the user with their email and verification code.
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId',
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.passwordless.loginWithEmail({
+     *   email: 'foo@example.com',
+     *   code: 'ABC123'
+     * });
+     * ```
+     */
+    loginWithEmail(bodyParameters: LoginWithEmailRequest, options?: GrantOptions): Promise<JSONApiResponse<TokenSet>>;
+    /**
+     * Once you have a verification code, use this endpoint to login the user with their phone number and verification code.
+     *
+     * @example
+     * ```js
+     * const auth0 = new AuthenticationApi({
+     *    domain: 'my-domain.auth0.com',
+     *    clientId: 'myClientId',
+     *    clientSecret: 'myClientSecret'
+     * });
+     *
+     * await auth0.passwordless.loginWithSMS({
+     *   phone_number: '0777777777',
+     *   code: 'ABC123'
+     * });
+     * ```
+     */
+    loginWithSMS(bodyParameters: LoginWithSMSRequest, options?: GrantOptions): Promise<JSONApiResponse<TokenSet>>;
+}

package/dist/typings/index.d.ts

@@ -0,0 +1,2 @@
+export * from './management/index.js';
+export * from './auth/index.js';

package/dist/typings/lib/errors.d.ts

@@ -0,0 +1,34 @@
+import type { Headers } from 'node-fetch';
+/**
+ * Error thrown when the API returns an error response that can't be parsed to a more specific Error instance.
+ */
+export declare class ResponseError extends Error {
+    statusCode: number;
+    body: string;
+    headers: Headers;
+    name: "ResponseError";
+    constructor(statusCode: number, body: string, headers: Headers, msg?: string);
+}
+/**
+ * Error thrown when the request is aborted due to a timeout.
+ */
+export declare class TimeoutError extends Error {
+    name: "TimeoutError";
+    constructor();
+}
+/**
+ * Error thrown when there is a network error.
+ */
+export declare class FetchError extends Error {
+    cause: Error;
+    name: "FetchError";
+    constructor(cause: Error, msg?: string);
+}
+/**
+ * Error thrown when a required argument was not provided.
+ */
+export declare class RequiredError extends Error {
+    field: string;
+    name: "RequiredError";
+    constructor(field: string, msg?: string);
+}

package/dist/typings/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './errors.js';
+export * from './models.js';
+export { RetryConfiguration } from './retry.js';

package/dist/typings/lib/middleware/telemetry-middleware.d.ts

@@ -0,0 +1,12 @@
+import { Middleware, ClientOptions, FetchParams, RequestContext } from '../runtime.js';
+/**
+ * @private
+ */
+export declare class TelemetryMiddleware implements Middleware {
+    clientInfo: {
+        name: string;
+        [key: string]: unknown;
+    };
+    constructor(options: ClientOptions);
+    pre?(context: RequestContext): Promise<FetchParams | void>;
+}

package/dist/typings/lib/models.d.ts

@@ -0,0 +1,124 @@
+import type { RequestInit, RequestInfo, Response, Headers } from 'node-fetch';
+import { RetryConfiguration } from './retry.js';
+/**
+ * @private
+ */
+export type FetchAPI = (url: URL | RequestInfo, init: RequestInit) => Promise<Response>;
+export interface ClientOptions extends Omit<Configuration, 'baseUrl' | 'parseError'> {
+    telemetry?: boolean;
+    clientInfo?: {
+        name: string;
+        [key: string]: unknown;
+    };
+}
+export interface Configuration {
+    baseUrl: string;
+    parseError: (response: Response) => Promise<Error>;
+    /**
+     * Provide your own fetch implementation.
+     */
+    fetchApi?: FetchAPI;
+    /**
+     * Provide a middleware that will run either before the request, after the request or when the request fails.
+     */
+    middleware?: Middleware[];
+    /**
+     * Pass your own http agent to support proxies.
+     */
+    agent?: RequestInit['agent'];
+    /**
+     * Custom headers that will be added to every request.
+     */
+    headers?: HTTPHeaders;
+    /**
+     * Timeout in ms before aborting the request (default 10,000)
+     */
+    timeoutDuration?: number;
+    /**
+     * Retry configuration.
+     */
+    retry?: RetryConfiguration;
+}
+export interface RequestOpts {
+    path: string;
+    method: HTTPMethod;
+    headers?: HTTPHeaders;
+    query?: HTTPQuery;
+    body?: HTTPBody;
+}
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+export type HTTPHeaders = {
+    [key: string]: string;
+};
+export type HTTPQuery = {
+    [key: string]: string | number | null | boolean | Array<string | number | null | boolean> | HTTPQuery;
+};
+export type HTTPBody = any | FormData | URLSearchParams;
+export type HTTPRequestInit = {
+    headers?: HTTPHeaders;
+    method: HTTPMethod;
+    credentials?: RequestCredentials;
+    body?: HTTPBody;
+};
+export type InitOverrideFunction = (requestContext: {
+    init: HTTPRequestInit;
+    context: RequestOpts;
+}) => Promise<RequestInit>;
+export type InitOverride = RequestInit | InitOverrideFunction;
+export interface ApiResponse<T> {
+    data: T;
+    headers: Headers;
+    status: number;
+    statusText: string;
+}
+export declare class JSONApiResponse<T> implements ApiResponse<T> {
+    data: T;
+    headers: Headers;
+    readonly status: number;
+    readonly statusText: string;
+    constructor(data: T, headers: Headers, status: number, statusText: string);
+    static fromResponse<T = unknown>(raw: Response): Promise<JSONApiResponse<T>>;
+}
+export declare class VoidApiResponse implements ApiResponse<undefined> {
+    headers: Headers;
+    readonly status: number;
+    readonly statusText: string;
+    data: undefined;
+    constructor(headers: Headers, status: number, statusText: string);
+    static fromResponse(raw: Response): Promise<VoidApiResponse>;
+}
+export declare class TextApiResponse implements ApiResponse<string> {
+    data: string;
+    headers: Headers;
+    readonly status: number;
+    readonly statusText: string;
+    constructor(data: string, headers: Headers, status: number, statusText: string);
+    static fromResponse(raw: Response): Promise<TextApiResponse>;
+}
+export interface FetchParams {
+    url: URL | RequestInfo;
+    init: RequestInit;
+}
+export interface RequestContext {
+    fetch: FetchAPI;
+    url: URL | RequestInfo;
+    init: RequestInit;
+}
+export interface ResponseContext {
+    fetch: FetchAPI;
+    url: URL | RequestInfo;
+    init: RequestInit;
+    response: Response;
+}
+export interface ErrorContext {
+    fetch: FetchAPI;
+    url: URL | RequestInfo;
+    init: RequestInit;
+    error: unknown;
+    response?: Response;
+}
+export interface Middleware {
+    pre?(context: RequestContext): Promise<FetchParams | void> | FetchParams | void;
+    post?(context: ResponseContext): Promise<Response | void> | Response | void;
+    onError?(context: ErrorContext): Promise<Response | void> | Response | void;
+}

package/dist/typings/lib/retry.d.ts

@@ -0,0 +1,27 @@
+import type { Response } from 'node-fetch';
+/**
+ * Configure the retry logic for http calls.
+ * By default, this retries any request that returns a 429 3 times.
+ */
+export interface RetryConfiguration {
+    /**
+     * Configure the usage of retries.
+     * Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Configure the max amount of retries the SDK should do.
+     * Defaults to 5.
+     */
+    maxRetries?: number;
+    /**
+     * Status Codes on which the SDK should trigger retries.
+     * Defaults to [429].
+     */
+    retryWhen?: number[];
+}
+/**
+ * @private
+ * Function that retries the provided action callback for a configurable amount of time, defaults to 3.
+ */
+export declare function retry(action: () => Promise<Response>, { maxRetries, retryWhen }: RetryConfiguration): Promise<Response>;