II Integration Helper

A TypeScript library that provides helper functions for implementing the Proxy Web App component of Internet Identity (II) integration for mobile applications. This library follows the secure integration pattern described in the Internet Computer documentation.

Overview

This library implements the Proxy Web App component of the secure Internet Identity integration pattern for mobile applications. It helps create a secure bridge between mobile applications and Internet Identity by:

1. Generating an intermediate session key
2. Initiating the II client authentication protocol using this intermediate key
3. Creating a delegation chain that allows the mobile application to use their session key
4. Returning the delegation chain to the mobile app using app links/universal links and URI fragments

This approach prevents delegation theft attacks that could occur with naive implementations.

Installation

npm install ii-integration-helper

Dependencies

Peer Dependencies

These dependencies need to be installed in your project:

npm install @dfinity/agent @dfinity/identity @dfinity/auth-client

• @dfinity/agent: For Internet Computer agent functionality
• @dfinity/identity: For identity and delegation management
• @dfinity/auth-client: For authentication client functionality

Regular Dependencies

The following dependencies are included in the package:

• canister-manager: For canister URL management

Features

• Secure Internet Identity authentication integration for mobile applications
• Intermediate session key generation and management
• Delegation chain creation and verification
• Deep linking support for various platforms (ICP, Expo, native apps)
• Public key handling
• Error formatting and rendering
• Button setup and event handling

Usage

Basic Usage

import {
  buildParams,
  setupLoginButtonHandler,
  prepareButtons,
} from 'ii-integration-helper';

// Build parameters for II integration
const params = buildParams({
  localIPAddress: '127.0.0.1',
  dfxNetwork: 'local',
  internetIdentityCanisterId: 'rdmx6-jaaaa-aaaaa-aaadq-cai',
  frontendCanisterId: 'rrkah-fqaaa-aaaaa-aaaaq-cai',
  expoScheme: 'myapp',
  window: window,
});

// Prepare buttons
const { iiLoginButton, backToAppButton } = prepareButtons();

// Setup login button handler
await setupLoginButtonHandler({
  iiLoginButton,
  backToAppButton,
  deepLink: params.deepLink,
  appPublicKey: params.appPublicKey,
  iiUri: params.iiUri,
  window: window,
});

Deep Linking

import { buildDeepLink, DeepLinkType } from 'ii-integration-helper';

// Build a deep link for different platforms
const deepLink = buildDeepLink({
  deepLinkType: 'icp' as DeepLinkType,
  localIPAddress: '127.0.0.1',
  dfxNetwork: 'local',
  frontendCanisterId: 'rrkah-fqaaa-aaaaa-aaaaq-cai',
  expoScheme: 'myapp',
});

Delegation Chain

import {
  buildMiddleToAppDelegationChain,
  buildURIFragment,
} from 'ii-integration-helper';

// Build a delegation chain
const delegationChain = await buildMiddleToAppDelegationChain({
  middleDelegationIdentity,
  appPublicKey,
  expiration: new Date(Date.now() + 1000 * 60 * 15), // 15 minutes
});

// Build a URI fragment for the delegation
const uriFragment = buildURIFragment(delegationChain);

Security Considerations

This library implements the secure integration pattern for Internet Identity on mobile devices as described in the Internet Computer documentation. Key security features include:

1. Intermediate Session Key: The library generates an intermediate session key that is stored by the web app proxy frontend, preventing delegation theft.

2. Delegation Chain: The library creates a delegation chain consisting of two delegations:

   • First delegation: From the II canister key to the intermediate key (generated by the II canister)
   • Second delegation: From the intermediate key to the mobile app public key (signed by the proxy frontend)

3. Secure Communication: The delegation chain is returned to the mobile app using app links/universal links and URI fragments, which prevents delegation leakage.

4. Origin Verification: The library helps verify the origin of authentication requests to prevent phishing attacks.

API Reference

Core Functions

• buildParams: Builds parameters for II integration
• buildDeepLink: Creates deep links for different platforms
• buildIIUri: Builds the Internet Identity URI
• buildAppPublicKey: Converts a hex string to a PublicKey
• buildDelegationString: Converts a DelegationChain to a string
• buildMiddleToAppDelegationChain: Creates a delegation chain
• buildURIFragment: Builds a URI fragment for delegation

UI Helpers

• prepareButtons: Prepares and validates UI buttons
• prepareLogin: Prepares the login process
• setupLoginButtonHandler: Sets up the login button handler
• renderError: Renders error messages
• formatError: Formats error messages

Environment Detection

• determineIframe: Determines if the current window is an iframe
• handleNativeAppDelegation: Handles delegation in a native app
• sendDelegationToParent: Sends delegation to the parent window

Development

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Run tests with coverage
npm run test:coverage

License

MIT