ic-auth/dist/index.d.ts

A simple, modular package for integrating Internet Computer authentication providers into your app.

import { Agent } from '@dfinity/agent';
import { InterfaceFactory } from '@dfinity/candid/lib/cjs/idl';
import { ActorSubclass, ActorMethod } from '@dfinity/agent';
/**
 * Represents an authenticated user session.
 */
export type UserObject = {
    principal: string;
    agent: Agent | undefined;
    provider: string;
};
/**
 * Authenticate the user with the Stoic Wallet provider and return a connected UserObject.
 *
 * This flow checks if Stoic is already connected, otherwise prompts the user to connect.
 * If successful, it creates a new Agent tied to the identity and returns the principal and agent.
 *
 * @param host - The IC replica host to connect to (e.g., local or mainnet).
 * @returns A Promise resolving to a UserObject containing principal, agent, and provider info.
 * @throws If Stoic identity cannot be loaded or connection fails.
 *
 * @todo Stoic is currently known to throw a cookie-related error in some browsers.
 *       This may be fixed in a later version.
 */
export declare const StoicLogin: (host: string) => Promise<UserObject>;
/**
 * Logs in with Plug Wallet and returns the authenticated user's agent and information.
 *
 * @param whitelist - An array of canister IDs the app will access using Plug Wallet.
 * @param host - The URL of the Internet Computer replica to connect to.
 *               Use "https://icp0.io" or "https://ic0.app" for mainnet or "http://127.0.0.1:<YourDFXPort>" for local development.
 * @returns A Promise that resolves to a UserObject containing the agent, principal, and provider name.
 */
export declare const PlugLogin: (whitelist: string[], host: string) => Promise<UserObject>;
/**
 * Authenticate the user using NFID and return a connected UserObject.
 *
 * This flow uses DFINITY's AuthClient with NFID as the identity provider.
 * It constructs the NFID authorization URL with application name and logo,
 * creates a modern Agent tied to the authenticated identity, and resolves the user details.
 *
 * @param host - The IC replica host to connect to (mainnet or local).
 * @returns A Promise resolving to a UserObject containing principal, agent, and provider info.
 * @throws If creating the AuthClient or login flow fails.
 */
export declare const NFIDLogin: (host: string) => Promise<UserObject>;
/**
 * Authenticate the user using Internet Identity and return a connected UserObject.
 *
 * This flow uses DFINITY's AuthClient to open the Internet Identity login,
 * creates an Agent with the returned identity, and resolves the user details.
 * It handles both mainnet and local environments by conditionally fetching the root key.
 *
 * @param host - The IC replica host to connect to (mainnet or local).
 * @returns A Promise resolving to a UserObject containing principal, agent, and provider info.
 * @throws If creating the AuthClient or login flow fails.
 */
export declare const IdentityLogin: (host: string) => Promise<UserObject>;
/**
 * Create an actor for any canister using a provided agent.
 * @param agent - The authenticated or anonymous Agent instance.
 * @param idl - The IDL factory for the target canister.
 * @param canisterId - The canister ID to connect to.
 * @returns A typed Actor subclass for the canister.
 */
export declare const CreateActor: (agent: Agent, idl: InterfaceFactory, canisterId: string) => Promise<ActorSubclass<Record<string, ActorMethod<unknown[], unknown>>>>;
/**
 * Create an anonymous agent for public queries or read-only calls.
 * @param host - Optional IC replica host (defaults to mainnet).
 * @returns An Agent instance with no identity attached.
 */
export declare const CreateAnonAgent: (host: string) => Promise<Agent>;