@faable/auth-js 1.3.0 → 1.3.2

package/dist/dts/Base.d.ts

@@ -0,0 +1,7 @@
+import { BaseLog, BaseLogOptions } from "./BaseLog";
+export declare abstract class Base extends BaseLog {
+    private static nextInstanceID;
+    private instanceID;
+    constructor(config?: BaseLogOptions);
+    extraPrint(): string;
+}

package/dist/dts/BaseLog.d.ts

@@ -0,0 +1,10 @@
+export type BaseLogOptions = {
+    debug?: boolean | ((message: string, ...args: any[]) => void);
+};
+export declare abstract class BaseLog {
+    protected logDebugMessages: boolean;
+    protected logger: (message: string, ...args: any[]) => void;
+    constructor(config?: BaseLogOptions);
+    protected extraPrint?(): string;
+    protected _debug(...args: any[]): this;
+}

package/dist/dts/FaableAuthApi.d.ts

@@ -0,0 +1,13 @@
+import { BaseLog, BaseLogOptions } from "./BaseLog";
+import { AuthError } from "./lib/errors";
+export default class FaableAuthApi extends BaseLog {
+    base_url: string;
+    constructor(base_url: string, config: BaseLogOptions);
+    protected extraPrint(): string;
+    signOut(params: {
+        client_id: string;
+    }): Promise<{
+        data: null;
+        error: AuthError | null;
+    }>;
+}

package/dist/dts/FaableAuthClient.d.ts

@@ -0,0 +1,231 @@
+import { AuthFlowType, SupportedStorage, SignInWithOAuthConnection, OAuthResponse, Subscription, InitializeResult, CallRefreshTokenResult } from "./lib/types";
+import { FaableAuthClientConfig, AuthResponse, AuthChangeEvent } from "./lib/types";
+import { Session, SignOut } from "./lib/types";
+import { Deferred } from "./lib/helpers";
+import { AuthError } from "./lib/errors";
+import FaableAuthApi from "./FaableAuthApi";
+import { Base } from "./Base";
+import { Lock } from "./lock/Lock";
+export declare class FaableAuthClient extends Base {
+    domainUrl: string;
+    tokenIssuer: string;
+    redirect_uri: string;
+    scope?: string;
+    sessionCheckExpiryDays: number;
+    protected initializePromise: Promise<InitializeResult> | null;
+    protected detectSessionInUrl: boolean;
+    protected storageKey: string;
+    protected clientId: string;
+    protected flowType: AuthFlowType;
+    protected storage: SupportedStorage;
+    protected api: FaableAuthApi;
+    protected autoRefreshToken: boolean;
+    protected autoRefreshTicker: ReturnType<typeof setInterval> | null;
+    protected visibilityChangedCallback: (() => Promise<any>) | null;
+    protected refreshingDeferred: Deferred<CallRefreshTokenResult> | null;
+    /**
+     * Used to broadcast state change events to other tabs listening.
+     */
+    protected broadcastChannel: BroadcastChannel | null;
+    protected stateChangeEmitters: Map<string, Subscription>;
+    protected lock: Lock;
+    constructor(config: FaableAuthClientConfig);
+    /**
+     * Initializes the client session either from the url or from storage.
+     * This method is automatically called when instantiating the client, but should also be called
+     * manually when checking for an error from an auth redirect (oauth, magiclink, password recovery, etc).
+     */
+    initialize(): Promise<InitializeResult>;
+    /**
+     * IMPORTANT:
+     * 1. Never throw in this method, as it is called from the constructor
+     * 2. Never return a session from this method as it would be cached over
+     *    the whole lifetime of the client
+     */
+    private _initialize;
+    /**
+     * Gets the session data from a URL string
+     */
+    private _getSessionFromURL;
+    private _exchangeCodeForSession;
+    /**
+     * Registers callbacks on the browser / platform, which in-turn run
+     * algorithms when the browser window/tab are in foreground. On non-browser
+     * platforms it assumes always foreground.
+     */
+    private _handleVisibilityChange;
+    /**
+     * Callback registered with `window.addEventListener('visibilitychange')`.
+     */
+    private _onVisibilityChanged;
+    /**
+     * Recovers the session from LocalStorage and refreshes
+     * Note: this method is async to accommodate for AsyncStorage e.g. in React native.
+     */
+    private _recoverAndRefresh;
+    /**
+     * Removes any registered visibilitychange callback.
+     *
+     * {@see #startAutoRefresh}
+     * {@see #stopAutoRefresh}
+     */
+    private _removeVisibilityChangedCallback;
+    /**
+     * Starts an auto-refresh process in the background. The session is checked
+     * every few seconds. Close to the time of expiration a process is started to
+     * refresh the session. If refreshing fails it will be retried for as long as
+     * necessary.
+     *
+     * If you set the {@link GoTrueClientOptions#autoRefreshToken} you don't need
+     * to call this function, it will be called for you.
+     *
+     * On browsers the refresh process works only when the tab/window is in the
+     * foreground to conserve resources as well as prevent race conditions and
+     * flooding auth with requests. If you call this method any managed
+     * visibility change callback will be removed and you must manage visibility
+     * changes on your own.
+     *
+     * On non-browser platforms the refresh process works *continuously* in the
+     * background, which may not be desirable. You should hook into your
+     * platform's foreground indication mechanism and call these methods
+     * appropriately to conserve resources.
+     *
+     * {@see #stopAutoRefresh}
+     */
+    startAutoRefresh(): Promise<void>;
+    /**
+     * This is the private implementation of {@link #startAutoRefresh}. Use this
+     * within the library.
+     */
+    private _startAutoRefresh;
+    /**
+     * This is the private implementation of {@link #stopAutoRefresh}. Use this
+     * within the library.
+     */
+    private _stopAutoRefresh;
+    /**
+     * Runs the auto refresh token tick.
+     */
+    private _autoRefreshTokenTick;
+    /**
+     * Checks if the current URL and backing storage contain parameters given by a PKCE flow
+     */
+    private _isPKCEFlow;
+    /**
+     * Checks if the current URL contains parameters given by an implicit oauth grant flow (https://www.rfc-editor.org/rfc/rfc6749.html#section-4.2)
+     */
+    private _isImplicitGrantFlow;
+    private _scope;
+    private _getUrlForConnection;
+    signInWithOauthConnection(credentials: SignInWithOAuthConnection): Promise<OAuthResponse>;
+    signInWithUsernamePassword(data: {
+        username: string;
+        password: string;
+        redirect_uri?: string;
+    }): Promise<void>;
+    private _handleConnectionSignIn;
+    /**
+     * Sets the session data from the current session. If the current session is expired, setSession will take care of refreshing it to obtain a new session.
+     * If the refresh token or access token in the current session is invalid, an error will be thrown.
+     * @param currentSession The current session that minimally contains an access token and refresh token.
+     */
+    setSession(currentSession: {
+        access_token: string;
+        refresh_token: string;
+    }): Promise<AuthResponse>;
+    /**
+     * Returns the session, refreshing it if necessary.
+     *
+     * The session returned can be null if the session is not detected which can happen in the event a user is not signed-in or has logged out.
+     *
+     * **IMPORTANT:** This method loads values directly from the storage attached
+     * to the client. If that storage is based on request cookies for example,
+     * the values in it may not be authentic and therefore it's strongly advised
+     * against using this method and its results in such circumstances. A warning
+     * will be emitted if this is detected. Use {@link #getUser()} instead.
+     */
+    getSession(): Promise<{
+        data: {
+            session: Session;
+        };
+        error: null;
+    } | {
+        data: {
+            session: null;
+        };
+        error: AuthError;
+    } | {
+        data: {
+            session: null;
+        };
+        error: null;
+    }>;
+    /**
+     * Use instead of {@link #getSession} inside the library. It is
+     * semantically usually what you want, as getting a session involves some
+     * processing afterwards that requires only one client operating on the
+     * session at once across multiple tabs or processes.
+     */
+    private _useSession;
+    /**
+     * NEVER USE DIRECTLY!
+     *
+     * Always use {@link #_useSession}.
+     */
+    private __loadSession;
+    private _removeSession;
+    private _isValidSession;
+    protected _setSession(currentSession: {
+        access_token: string;
+        refresh_token: string;
+    }): Promise<AuthResponse>;
+    /**
+     * set currentSession and currentUser
+     * process to _startAutoRefreshToken if possible
+     */
+    private _saveSession;
+    private _getUser;
+    private _callRefreshToken;
+    /**
+     * Generates a new JWT.
+     * @param refreshToken A valid refresh token that was returned on login.
+     */
+    private _refreshAccessToken;
+    private _notifyAllSubscribers;
+    /**
+     * Inside a browser context, `signOut()` will remove the logged in user from the browser session and log them out - removing all items from localstorage and then trigger a `"SIGNED_OUT"` event.
+     *
+     * For server-side management, you can revoke all refresh tokens for a user by passing a user's JWT through to `auth.api.signOut(JWT: string)`.
+     * There is no way to revoke a user's access token jwt until it expires. It is recommended to set a shorter expiry on the jwt for this reason.
+     *
+     * If using `others` scope, no `SIGNED_OUT` event is fired!
+     */
+    signOut(options?: SignOut): Promise<{
+        error: AuthError | null;
+    }>;
+    protected _signOut({ scope }?: SignOut): Promise<{
+        error: AuthError | null;
+    }>;
+    /**
+     * Receive a notification every time an auth event happens.
+     * @param callback A callback function to be invoked when an auth event happens.
+     */
+    onAuthStateChange(callback: (event: AuthChangeEvent, session: Session | null) => void | Promise<void>): {
+        data: {
+            subscription: Subscription;
+        };
+    };
+    private _emitInitialSession;
+    /**
+     * Returns a new session, regardless of expiry status.
+     * Takes in an optional current session. If not passed in, then refreshSession() will attempt to retrieve it from getSession().
+     * If the current session's refresh token is invalid, an error will be thrown.
+     * @param currentSession The current session. If passed in, it must contain a refresh token.
+     */
+    refreshSession(currentSession?: {
+        refresh_token: string;
+    }): Promise<AuthResponse>;
+    protected _refreshSession(currentSession?: {
+        refresh_token: string;
+    }): Promise<AuthResponse>;
+}

package/dist/dts/entrypoints/faableauth.d.ts

@@ -0,0 +1,6 @@
+import { FaableAuthClient } from "../FaableAuthClient";
+import { FaableAuthClientConfig } from "../lib/types";
+import { Session, User } from "../lib/types";
+import { AuthError } from "../lib/errors";
+export declare const createClient: (config: FaableAuthClientConfig) => FaableAuthClient;
+export { Session, User, FaableAuthClient, AuthError };

package/dist/dts/lib/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const GOTRUE_URL = "http://localhost:9999";
+export declare const STORAGE_KEY = "faable.auth.token";
+export declare const EXPIRY_MARGIN = 10;
+export declare const API_VERSION_HEADER_NAME = "X-Faableauth-Api-Version";
+export declare const API_VERSIONS: {
+    "2024-01-01": {
+        timestamp: number;
+        name: string;
+    };
+};

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

@@ -0,0 +1,82 @@
+/**
+ * Known error codes. Note that the server may also return other error codes
+ * not included in this list (if the client library is older than the version
+ * on the server).
+ */
+export type ErrorCode = "unexpected_failure" | "validation_failed" | "bad_json" | "email_exists" | "phone_exists" | "bad_jwt" | "not_admin" | "no_authorization" | "user_not_found" | "session_not_found" | "flow_state_not_found" | "flow_state_expired" | "signup_disabled" | "user_banned" | "provider_email_needs_verification" | "invite_not_found" | "bad_oauth_state" | "bad_oauth_callback" | "oauth_provider_not_supported" | "unexpected_audience" | "single_identity_not_deletable" | "email_conflict_identity_not_deletable" | "identity_already_exists" | "email_provider_disabled" | "phone_provider_disabled" | "too_many_enrolled_mfa_factors" | "mfa_factor_name_conflict" | "mfa_factor_not_found" | "mfa_ip_address_mismatch" | "mfa_challenge_expired" | "mfa_verification_failed" | "mfa_verification_rejected" | "insufficient_aal" | "captcha_failed" | "saml_provider_disabled" | "manual_linking_disabled" | "sms_send_failed" | "email_not_confirmed" | "phone_not_confirmed" | "reauth_nonce_missing" | "saml_relay_state_not_found" | "saml_relay_state_expired" | "saml_idp_not_found" | "saml_assertion_no_user_id" | "saml_assertion_no_email" | "user_already_exists" | "sso_provider_not_found" | "saml_metadata_fetch_failed" | "saml_idp_already_exists" | "sso_domain_already_exists" | "saml_entity_id_mismatch" | "conflict" | "provider_disabled" | "user_sso_managed" | "reauthentication_needed" | "same_password" | "reauthentication_not_valid" | "otp_expired" | "otp_disabled" | "identity_not_found" | "weak_password" | "over_request_rate_limit" | "over_email_send_rate_limit" | "over_sms_send_rate_limit" | "bad_code_verifier";
+export declare class AuthError extends Error {
+    /**
+     * Error code associated with the error. Most errors coming from
+     * HTTP responses will have a code, though some errors that occur
+     * before a response is received will not have one present. In that
+     * case {@link #status} will also be undefined.
+     */
+    code: ErrorCode | string | undefined;
+    /** HTTP status code that caused the error. */
+    status: number | undefined;
+    protected __isAuthError: boolean;
+    constructor(message: string, status?: number, code?: string);
+}
+export declare class CustomAuthError extends AuthError {
+    name: string;
+    status: number;
+    constructor(message: string, name: string, status: number, code: string | undefined);
+}
+export declare class AuthSessionMissingError extends CustomAuthError {
+    constructor();
+}
+export declare function isAuthError(error: unknown): error is AuthError;
+export declare class AuthApiError extends AuthError {
+    status: number;
+    constructor(message: string, status: number, code: string | undefined);
+}
+export declare function isAuthApiError(error: unknown): error is AuthApiError;
+export declare class AuthImplicitGrantRedirectError extends CustomAuthError {
+    details: {
+        error: string;
+        code: string;
+    } | null;
+    constructor(message: string, details?: {
+        error: string;
+        code: string;
+    } | null);
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number;
+        details: {
+            error: string;
+            code: string;
+        } | null;
+    };
+}
+export declare class AuthPKCEGrantCodeExchangeError extends CustomAuthError {
+    details: {
+        error: string;
+        code: string;
+    } | null;
+    constructor(message: string, details?: {
+        error: string;
+        code: string;
+    } | null);
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number;
+        details: {
+            error: string;
+            code: string;
+        } | null;
+    };
+}
+export declare class AuthUnknownError extends AuthError {
+    originalError: unknown;
+    constructor(message: string, originalError: unknown);
+}
+export declare class AuthInvalidTokenResponseError extends CustomAuthError {
+    constructor();
+}
+export declare class AuthRetryableFetchError extends CustomAuthError {
+    constructor(message: string, status: number);
+}
+export declare function isAuthRetryableFetchError(error: unknown): error is AuthRetryableFetchError;

package/dist/dts/lib/fetch.d.ts

@@ -0,0 +1,11 @@
+export type JsonResponse<T = any> = {
+    data: T | null;
+    error?: any;
+};
+type RequestInitWithToken = RequestInit & {
+    token: string;
+    raw: boolean;
+};
+export declare const _post: <T>(url: string, data: object, options?: Partial<RequestInitWithToken>) => Promise<JsonResponse<T>>;
+export declare const _get: <T>(url: string, options?: Partial<RequestInitWithToken>) => Promise<JsonResponse<T>>;
+export {};

package/dist/dts/lib/globals.d.ts

@@ -0,0 +1,4 @@
+declare const win: (Window & typeof globalThis) | undefined;
+export declare const document: Document;
+export { win as window };
+export declare const fetch: ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) & typeof globalThis.fetch;

package/dist/dts/lib/helpers.d.ts

@@ -0,0 +1,52 @@
+import { AuthResponse, SupportedStorage, User } from "./types";
+import { JsonResponse } from "./fetch";
+export declare function decodeBase64URL(value: string): string;
+export declare function generatePKCEVerifier(): string;
+export declare function generatePKCEChallenge(verifier: string): Promise<string>;
+export declare function getCodeChallengeAndMethod(storage: SupportedStorage, storageKey: string, isPasswordRecovery?: boolean): Promise<string[]>;
+export declare const isBrowser: () => boolean;
+/**
+ * Checks whether localStorage is supported on this browser.
+ */
+export declare const supportsLocalStorage: () => boolean;
+export declare function uuid(): string;
+export type RawAuthResponse = {
+    expires_at: number;
+    expires_in: number;
+    user: User;
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+};
+export declare function expiresAt(expiresIn: number): number;
+export declare function _sessionResponse({ data, }: JsonResponse<Partial<RawAuthResponse>>): AuthResponse;
+/**
+ * A deferred represents some asynchronous work that is not yet finished, which
+ * may or may not culminate in a value.
+ * Taken from: https://github.com/mike-north/types/blob/master/src/async.ts
+ */
+export declare class Deferred<T = any> {
+    static promiseConstructor: PromiseConstructor;
+    readonly promise: PromiseLike<T>;
+    readonly resolve: (value?: T | PromiseLike<T>) => void;
+    readonly reject: (reason?: any) => any;
+    constructor();
+}
+/**
+ * Converts the provided async function into a retryable function. Each result
+ * or thrown error is sent to the isRetryable function which should return true
+ * if the function should run again.
+ */
+export declare function retryable<T>(fn: (attempt: number) => Promise<T>, isRetryable: (attempt: number, error: any | null, result?: T) => boolean): Promise<T>;
+/**
+ * Creates a promise that resolves to null after some time.
+ */
+export declare function sleep(time: number): Promise<null>;
+export declare const checkExpiresInTime: ({ expires_in, expires_at, refreshTick, }: {
+    expires_in: string;
+    expires_at?: string;
+    refreshTick: number;
+}) => {
+    expiresIn: number;
+    expiresAt: number;
+};

package/dist/dts/lib/jwt.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @ignore
+ */
+export interface JWTVerifyOptions {
+    iss: string;
+    aud: string;
+    id_token: string;
+    nonce?: string;
+    leeway?: number;
+    max_age?: number;
+    organizationId?: string;
+    now?: number;
+}
+export interface IdToken {
+    __raw: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    middle_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    email?: string;
+    email_verified?: boolean;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: string;
+    updated_at?: string;
+    iss?: string;
+    aud?: string;
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    jti?: string;
+    azp?: string;
+    nonce?: string;
+    auth_time?: string;
+    at_hash?: string;
+    c_hash?: string;
+    acr?: string;
+    amr?: string;
+    sub_jwk?: string;
+    cnf?: string;
+    sid?: string;
+    org_id?: string;
+    [key: string]: any;
+}
+export declare function decodeJWTPayload(token: string): any;
+export declare const verify: (options: JWTVerifyOptions) => any;

package/dist/dts/lib/local-storage.d.ts

@@ -0,0 +1,12 @@
+import { SupportedStorage } from "./types";
+/**
+ * Provides safe access to the globalThis.localStorage property.
+ */
+export declare const localStorageAdapter: SupportedStorage;
+/**
+ * Returns a localStorage-like object that stores the key-value pairs in
+ * memory.
+ */
+export declare function memoryLocalStorageAdapter(store?: {
+    [key: string]: string;
+}): SupportedStorage;

package/dist/dts/lib/storage_helpers.d.ts

@@ -0,0 +1,4 @@
+import { SupportedStorage } from "./types";
+export declare const setItemAsync: (storage: SupportedStorage, key: string, data: any) => Promise<void>;
+export declare const getItemAsync: (storage: SupportedStorage, key: string) => Promise<unknown>;
+export declare const removeItemAsync: (storage: SupportedStorage, key: string) => Promise<void>;