@passageidentity/passage-flex-node/dist/index.d.ts

Passkey Flex for Node.js - Add passkey authentication to your own Node.js authentication flows with Passage by 1Password

/**
 * PassageFlex configuration object
 */
interface PassageFlexConfig {
    /**
     * The Passage app ID
     */
    appId: string;
    /**
     * The Passage API key
     */
    apiKey: string;
}

interface ConfigurationParameters {
    basePath?: string;
    fetchApi?: FetchAPI;
    middleware?: Middleware[];
    queryParamsStringify?: (params: HTTPQuery) => string;
    username?: string;
    password?: string;
    apiKey?: string | Promise<string> | ((name: string) => string | Promise<string>);
    accessToken?: string | Promise<string> | ((name?: string, scopes?: string[]) => string | Promise<string>);
    headers?: HTTPHeaders;
    credentials?: RequestCredentials;
}
declare class Configuration {
    private configuration;
    constructor(configuration?: ConfigurationParameters);
    set config(configuration: Configuration);
    get basePath(): string;
    get fetchApi(): FetchAPI | undefined;
    get middleware(): Middleware[];
    get queryParamsStringify(): (params: HTTPQuery) => string;
    get username(): string | undefined;
    get password(): string | undefined;
    get apiKey(): ((name: string) => string | Promise<string>) | undefined;
    get accessToken(): ((name?: string, scopes?: string[]) => string | Promise<string>) | undefined;
    get headers(): HTTPHeaders | undefined;
    get credentials(): RequestCredentials | undefined;
}
declare class ResponseError extends Error {
    response: Response;
    name: "ResponseError";
    constructor(response: Response, msg?: string);
}
type FetchAPI = WindowOrWorkerGlobalScope['fetch'];
type HTTPHeaders = {
    [key: string]: string;
};
type HTTPQuery = {
    [key: string]: string | number | null | boolean | Array<string | number | null | boolean> | Set<string | number | null | boolean> | HTTPQuery;
};
interface FetchParams {
    url: string;
    init: RequestInit;
}
interface RequestContext {
    fetch: FetchAPI;
    url: string;
    init: RequestInit;
}
interface ResponseContext {
    fetch: FetchAPI;
    url: string;
    init: RequestInit;
    response: Response;
}
interface ErrorContext {
    fetch: FetchAPI;
    url: string;
    init: RequestInit;
    error: unknown;
    response?: Response;
}
interface Middleware {
    pre?(context: RequestContext): Promise<FetchParams | void>;
    post?(context: ResponseContext): Promise<Response | void>;
    onError?(context: ErrorContext): Promise<Response | void>;
}

/**
 * Passage Management API
 * Passage\'s management API to manage your Passage apps and users.
 *
 * The version of the OpenAPI document: 1
 * Contact: support@passage.id
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 */
/**
 * Contains the light and dark SVG icons that represent the brand of those devices
 * Values can be null or base64 encoded SVG. Example of SVG output:
 * data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGVuYWJsZS1iYWNrZ3JvdW5kPSJuZXcgMCAwIDE5MiAxOTIiIGhlaWdodD0iMjRweCIgdmlld0JveD0iMCAwIDE5MiAxOTIiIHdpZHRoPSIyNHB4Ij48cmVjdCBmaWxsPSJub25lIiBoZWlnaHQ9IjE5MiIgd2lkdGg9IjE5MiIgeT0iMCIvPjxnPjxwYXRoIGQ9Ik02OS4yOSwxMDZjLTMuNDYsNS45Ny05LjkxLDEwLTE3LjI5LDEwYy0xMS4wMywwLTIwLTguOTctMjAtMjBzOC45Ny0yMCwyMC0yMCBjNy4zOCwwLDEzLjgzLDQuMDMsMTcuMjksMTBoMjUuNTVDOTAuMyw2Ni41NCw3Mi44Miw1Miw1Miw1MkMyNy43NCw1Miw4LDcxLjc0LDgsOTZzMTkuNzQsNDQsNDQsNDRjMjAuODIsMCwzOC4zLTE0LjU0LDQyLjg0LTM0IEg2OS4yOXoiIGZpbGw9IiM0Mjg1RjQiLz48cmVjdCBmaWxsPSIjRkJCQzA0IiBoZWlnaHQ9IjI0IiB3aWR0aD0iNDQiIHg9Ijk0IiB5PSI4NCIvPjxwYXRoIGQ9Ik05NC4zMiw4NEg2OHYwLjA1YzIuNSwzLjM0LDQsNy40Nyw0LDExLjk1cy0xLjUsOC42MS00LDExLjk1VjEwOGgyNi4zMiBjMS4wOC0zLjgyLDEuNjgtNy44NCwxLjY4LTEyUzk1LjQxLDg3LjgyLDk0LjMyLDg0eiIgZmlsbD0iI0VBNDMzNSIvPjxwYXRoIGQ9Ik0xODQsMTA2djI2aC0xNnYtOGMwLTQuNDItMy41OC04LTgtOHMtOCwzLjU4LTgsOHY4aC0xNnYtMjZIMTg0eiIgZmlsbD0iIzM0QTg1MyIvPjxyZWN0IGZpbGw9IiMxODgwMzgiIGhlaWdodD0iMjQiIHdpZHRoPSI0OCIgeD0iMTM2IiB5PSI4NCIvPjwvZz48L3N2Zz4=
 * @export
 * @interface WebAuthnIcons
 */
interface WebAuthnIcons {
    /**
     *
     * @type {string}
     * @memberof WebAuthnIcons
     */
    light: string | null;
    /**
     *
     * @type {string}
     * @memberof WebAuthnIcons
     */
    dark: string | null;
}

/**
 * Passage Management API
 * Passage\'s management API to manage your Passage apps and users.
 *
 * The version of the OpenAPI document: 1
 * Contact: support@passage.id
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 */
/**
 * The type of this credential
 * @export
 */
declare const WebAuthnType: {
    readonly Passkey: "passkey";
    readonly SecurityKey: "security_key";
    readonly Platform: "platform";
};
type WebAuthnType = typeof WebAuthnType[keyof typeof WebAuthnType];

/**
 * Passage Management API
 * Passage\'s management API to manage your Passage apps and users.
 *
 * The version of the OpenAPI document: 1
 * Contact: support@passage.id
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 */

/**
 *
 * @export
 * @interface WebAuthnDevices
 */
interface WebAuthnDevices {
    /**
     * The first time this webAuthn device was used to authenticate the user
     * @type {Date}
     * @memberof WebAuthnDevices
     */
    createdAt: Date;
    /**
     * The CredID for this webAuthn device
     * @type {string}
     * @memberof WebAuthnDevices
     */
    credId: string;
    /**
     * The friendly name for the webAuthn device used to authenticate
     * @type {string}
     * @memberof WebAuthnDevices
     */
    friendlyName: string;
    /**
     * The ID of the webAuthn device used for authentication
     * @type {string}
     * @memberof WebAuthnDevices
     */
    id: string;
    /**
     * The last time this webAuthn device was used to authenticate the user
     * @type {Date}
     * @memberof WebAuthnDevices
     */
    lastLoginAt: Date;
    /**
     *
     * @type {WebAuthnType}
     * @memberof WebAuthnDevices
     */
    type: WebAuthnType;
    /**
     * The last time this webAuthn device was updated
     * @type {Date}
     * @memberof WebAuthnDevices
     */
    updatedAt: Date;
    /**
     * How many times this webAuthn device has been used to authenticate the user
     * @type {number}
     * @memberof WebAuthnDevices
     */
    usageCount: number;
    /**
     *
     * @type {WebAuthnIcons}
     * @memberof WebAuthnDevices
     */
    icons: WebAuthnIcons;
}

/**
 * Passage Management API
 * Passage\'s management API to manage your Passage apps and users.
 *
 * The version of the OpenAPI document: 1
 * Contact: support@passage.id
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 */
/**
 *
 * @export
 */
declare const UserStatus: {
    readonly Active: "active";
    readonly Inactive: "inactive";
    readonly Pending: "pending";
};
type UserStatus = typeof UserStatus[keyof typeof UserStatus];

interface PassageInstanceConfig {
    appId: string;
    apiConfiguration: Configuration;
}

/**
 * Base class for Passage sub-classes.
 */
declare class PassageBase {
    protected config: PassageInstanceConfig;
    /**
     * PassageBase class constructor.
     * @param {PassageInstanceConfig} config config properties for Passage instance
     */
    constructor(config: PassageInstanceConfig);
    /**
     * Handle errors from PassageFlex API
     * @param {unknown} err error from node-fetch request
     * @return {Promise<void>}
     */
    protected parseError(err: unknown): Promise<Error>;
}

/**
 * Auth class that provides methods for creating and validating passkey transactions.
 */
declare class Auth extends PassageBase {
    private readonly transactionClient;
    private readonly authClient;
    /**
     * Auth class constructor.
     * @param {PassageInstanceConfig} config config properties for Passage instance
     */
    constructor(config: PassageInstanceConfig);
    /**
     * Create a transaction to start a user's registration process
     *
     * @param {string} externalId The external ID of the user to register
     * @param {string} passkeyDisplayName The display name of the passkey to use
     * @return {Promise<string>} The transaction ID
     */
    createRegisterTransaction(externalId: string, passkeyDisplayName: string): Promise<string>;
    /**
     * Create a transaction to start a user's authentication process
     *
     * @param {string} externalId The external ID of the user to authenticate
     * @return {Promise<string>} The transaction ID
     */
    createAuthenticateTransaction(externalId: string): Promise<string>;
    /**
     * Verify the nonce received from a WebAuthn registration or authentication ceremony
     *
     * @param {string} nonce The nonce to verify
     * @return {Promise<string>} The unique identifier of the user associated with the nonce
     */
    verifyNonce(nonce: string): Promise<string>;
}

interface PassageUser {
    createdAt: Date;
    externalId: string;
    id: string;
    lastLoginAt: Date;
    loginCount: number;
    status: UserStatus;
    updatedAt: Date;
    userMetadata: object | null;
    webauthn: boolean;
    webauthnDevices: WebAuthnDevices[];
    webauthnTypes: WebAuthnType[];
}

/**
 * User class for handling operations to get and update user information.
 */
declare class User extends PassageBase {
    private readonly userClient;
    private readonly deviceClient;
    /**
     * User class constructor.
     * @param {PassageInstanceConfig} config config properties for Passage instance
     */
    constructor(config: PassageInstanceConfig);
    /**
     * Get a user by their external ID
     *
     * @param {string} externalId The external ID used to associate the user with Passage
     * @return {Promise<UserInfo>} Passage User object
     */
    get(externalId: string): Promise<PassageUser>;
    /**
     * Get a user's devices by their external ID
     *
     * @param {string} externalId The external ID used to associate the user with Passage
     * @return {Promise<WebAuthnDevices[]>} List of devices
     */
    listDevices(externalId: string): Promise<WebAuthnDevices[]>;
    /**
     * Revoke a user's device by their external ID and the device ID
     *
     * @param {string} externalId The external ID of the user whose device to revoke
     * @param {string} deviceId The device ID to revoke
     * @return {Promise<void>}
     */
    revokeDevice(externalId: string, deviceId: string): Promise<void>;
    /**
     * Get a user by their user ID
     *
     * @param {string} userId The Passage user ID
     * @return {Promise<UserInfo>} Passage User object
     */
    private getUserById;
    /**
     * Utility function to map the user info to the PassageUser type
     * @param {UserInfo} userInfo UserInfo object
     * @return {PassageUser} PassageUser object
     */
    private mapUserInfoToPassageUser;
}

/**
 * PassageFlex class used to get app info, create transactions, and verify nonces
 */
declare class PassageFlex {
    readonly auth: Auth;
    readonly user: User;
    /**
     * Initialize a new PassageFlex instance
     * @param {PassageFlexConfig} config The default config for Passage initialization
     */
    constructor(config: PassageFlexConfig);
}

declare const PassageErrorCode: {
    InternalServerError: "internal_server_error";
    UserAlreadyAdmin: "user_already_admin";
    UserAlreadyOrganizationMember: "user_already_organization_member";
    UserHasNoPasskeys: "user_has_no_passkeys";
    NativeClientAlreadyExists: "native_client_already_exists";
    FailedToSyncEmailPreferences: "failed_to_sync_email_preferences";
    AdminNotFound: "admin_not_found";
    ApiKeyNotFound: "api_key_not_found";
    AppNotFound: "app_not_found";
    DeviceNotFound: "device_not_found";
    DomainNotFound: "domain_not_found";
    EmailProviderNotFound: "email_provider_not_found";
    EmailTemplateNotFound: "email_template_not_found";
    EventNotFound: "event_not_found";
    FunctionNotFound: "function_not_found";
    FunctionSecretKeyNotFound: "function_secret_key_not_found";
    FunctionVersionNotFound: "function_version_not_found";
    MetadataFieldNotFound: "metadata_field_not_found";
    Oauth2AppNotFound: "oauth2_app_not_found";
    OrganizationMemberNotFound: "organization_member_not_found";
    SmsProviderNotFound: "sms_provider_not_found";
    SmsTemplateNotFound: "sms_template_not_found";
    SocialConnectionNotFound: "social_connection_not_found";
    UserNotFound: "user_not_found";
    NativeClientNotFound: "native_client_not_found";
    CannotCreateOrganizationBillingPortalSession: "cannot_create_organization_billing_portal_session";
    CannotCreateTransaction: "cannot_create_transaction";
    CannotDeleteAdmin: "cannot_delete_admin";
    CannotDeleteOrganizationMember: "cannot_delete_organization_member";
    CannotSelfUpdateOrganizationMember: "cannot_self_update_organization_member";
    OperationNotAllowed: "operation_not_allowed";
    AccessToken: "invalid_access_token";
    Nonce: "invalid_nonce";
    InvalidRequest: "invalid_request";
    CustomProviderRequired: "custom_provider_required";
};
type PassageErrorCode = (typeof PassageErrorCode)[keyof typeof PassageErrorCode];

/**
 * PassageError Class used to handle errors from PassageFlex
 */
declare class PassageError extends Error {
    readonly statusCode: number;
    readonly errorCode: PassageErrorCode;
    readonly message: string;
    name: string;
    /**
     * Initialize a new PassageError instance.
     * @param {number} statusCode status code from PassageFlex API
     * @param {string} errorCode error code from PassageFlex API
     * @param {string} message friendly message
     */
    private constructor();
    /**
     * Initialize a new PassageError instance.
     * @param {ResponseError} err error from node-fetch request
     * @return {Promise<PassageError>}
     */
    static fromResponseError(err: ResponseError): Promise<PassageError>;
}

export { Auth, PassageError, PassageErrorCode, PassageFlex, type PassageFlexConfig, type PassageUser, User, UserStatus, type WebAuthnDevices, type WebAuthnIcons, WebAuthnType };