ii-integration-helpers/dist/index.d.ts

A TypeScript library that provides helper functions for implementing the Proxy Web App component of Internet Identity (II) integration for mobile applications.

import { DelegationChain } from '@dfinity/identity';
import { DelegationIdentity } from '@dfinity/identity';
import { PublicKey } from '@dfinity/agent';

/**
 * ID for the back to app button
 */
export declare const BACK_TO_APP_BUTTON_ID = "back-to-app-button";

/**
 * Converts a hexadecimal public key string to an Ed25519PublicKey.
 *
 * @param {string} pubkey - The hexadecimal string representation of the public key.
 * @returns {PublicKey} The Ed25519 public key.
 */
export declare const buildAppPublicKey: (pubkey: string) => PublicKey;

/**
 * Builds a delegation string from a DelegationChain.
 *
 * @param {DelegationChain} delegationChain - The delegation chain to convert to a string.
 * @returns {string} The JSON string representation of the delegation.
 */
export declare const buildDelegationString: (delegationChain: DelegationChain) => string;

/**
 * Builds a delegation chain from the middle delegation identity to the application public key.
 *
 * @param {BuildMiddleToAppDelegationChainParams} params - The parameters containing the middle delegation identity and application public key.
 * @returns {Promise<DelegationChain>} A promise that resolves to the created delegation chain.
 */
export declare const buildMiddleToAppDelegationChain: ({ middleDelegationIdentity, appPublicKey, expiration, }: BuildMiddleToAppDelegationChainParams) => Promise<DelegationChain>;

/**
 * Parameters required for building the middle to app delegation chain.
 */
declare type BuildMiddleToAppDelegationChainParams = {
    /** The middle delegation identity containing the delegation information. */
    middleDelegationIdentity: DelegationIdentity;
    /** The application public key. */
    appPublicKey: PublicKey;
    /** The expiration time of the delegation. */
    expiration: Date;
};

/**
 * Builds the parameters required for the application.
 *
 * @param {BuildParamsParams} params - Configuration object containing necessary parameters.
 * @returns {BuildParamsResult} The built parameters including identity, iiUri, and deepLink.
 * @throws Will throw an error if pubkey or deep-link-type is missing in query string or if deep-link-type is not a valid DeepLinkType.
 */
export declare const buildParams: ({ localIPAddress, dfxNetwork, internetIdentityCanisterId, frontendCanisterId, expoScheme, }: BuildParamsParams) => BuildParamsResult;

/**
 * Parameters required to build the parameters for the application.
 */
declare type BuildParamsParams = {
    /**
     * The local IP address.
     */
    localIPAddress: string;
    /**
     * The DFX network.
     */
    dfxNetwork: string;
    /**
     * The canister ID for Internet Identity.
     */
    internetIdentityCanisterId: string;
    /**
     * The canister ID for the frontend.
     */
    frontendCanisterId: string;
    /**
     * The Expo scheme.
     */
    expoScheme: string;
};

/**
 * Interface representing the result of the buildParams function.
 */
export declare interface BuildParamsResult {
    appPublicKey: PublicKey;
    internetIdentityURL: URL;
    deepLink: URL;
    sessionId: string;
}

/**
 * Builds a URI fragment containing the encoded delegation information.
 * This is used for secure transmission of delegation data in the URL fragment
 * (the part after #) which is not sent to the server.
 *
 * @param {DelegationChain} delegationChain - The delegation chain containing the delegation information.
 * @returns {string} A URI fragment in the format 'delegation=<encoded_delegation_string>'.
 */
export declare const buildURIFragment: ({ delegationChain, sessionId, }: BuildURIFragmentParams) => string;

declare type BuildURIFragmentParams = {
    /** The delegation chain to encode */
    delegationChain: DelegationChain;
    /** The session ID to include in the URI fragment */
    sessionId: string;
};

/**
 * Error messages used in helper functions
 */
export declare const ERROR_MESSAGES: {
    /** Error message for login process failures */
    LOGIN_PROCESS: string;
};

/**
 * Formats an error message with a given prefix.
 *
 * @param {string} prefix - The prefix to add to the error message.
 * @param {unknown} error - The error to format.
 * @returns {string} The formatted error message.
 */
export declare const formatError: (prefix: string, error: unknown) => string;

/**
 * Handles delegation in a web or native app environment by setting up UI elements and redirecting.
 *
 * @param {HandleAppDelegationParams} params - The parameters for handling app delegation
 */
export declare const handleAppDelegation: ({ deepLink, delegationChain, sessionId, iiLoginButton, backToAppButton, }: HandleAppDelegationParams) => void;

/**
 * Parameters for handling app delegation
 */
export declare type HandleAppDelegationParams = {
    /** The deep link to redirect to after processing the delegation */
    deepLink: URL;
    /** The delegation chain to use */
    delegationChain: DelegationChain;
    /** The session ID to include in the URI fragment */
    sessionId: string;
    /** The II login button element */
    iiLoginButton: HTMLElement;
    /** The back to app button element */
    backToAppButton: HTMLElement;
};

/**
 * ID for the Internet Identity login button
 */
export declare const LOGIN_BUTTON_ID = "ii-login-button";

/**
 * Prepares and validates the required buttons for the Internet Identity login flow
 * @returns An object containing the II login button and back to app button
 * @throws Error if required buttons are not found
 */
export declare const prepareButtons: () => PrepareButtonsResult;

/**
 * Parameters for preparing the buttons
 */
declare type PrepareButtonsResult = {
    /** The Internet Identity login button element */
    iiLoginButton: HTMLButtonElement;
    /** The back to app button element */
    backToAppButton: HTMLButtonElement;
};

/**
 * Prepares the login process by creating an identity and an authentication client.
 * Returns a function that initiates the login process when called.
 *
 * @param {PrepareLoginParams} params - The parameters required to prepare the login.
 * @returns {Promise<() => Promise<DelegationIdentity>>} A promise that resolves to a function which handles the login process and returns the delegation identity.
 */
export declare const prepareLogin: ({ internetIdentityURL, }: PrepareLoginParams) => Promise<() => Promise<DelegationIdentity>>;

/**
 * Parameters required for preparing the login process.
 *
 * @typedef {Object} PrepareLoginParams@typedef {Object} PrepareLoginParams
 * @property {string} internetIdentityURL - The Internet Identity URL.
 */
declare type PrepareLoginParams = {
    internetIdentityURL: URL;
};

/**
 * Renders an error message in the designated error element.
 *
 * @param {string} message - The error message to display.
 * @returns {void}
 */
export declare const renderError: (message: string) => void;

/**
 * Sets up the click event handler for the Internet Identity login button
 * @param params - The parameters for setting up the login button handler
 */
export declare const setupLoginButtonHandler: ({ iiLoginButton, backToAppButton, deepLink, sessionId, appPublicKey, internetIdentityURL, ttlMs, }: SetupLoginButtonHandlerParams) => Promise<void>;

/**
 * Parameters for setting up the login button handler
 */
declare type SetupLoginButtonHandlerParams = {
    /** The Internet Identity login button element */
    iiLoginButton: HTMLButtonElement;
    /** The back to app button element */
    backToAppButton: HTMLButtonElement;
    /** The deep link URL for the app */
    deepLink: URL;
    /** The session ID to include in the URI fragment */
    sessionId: string;
    /** The public key for the app */
    appPublicKey: PublicKey;
    /** The Internet Identity URL */
    internetIdentityURL: URL;
    /** Time to live in milliseconds from the current time */
    ttlMs: number;
};

export { }