digiid-ts

A modern TypeScript implementation of the Digi-ID authentication protocol, inspired by the original digiid-js.

Provides utilities for generating Digi-ID URIs for QR code display and verifying the callback data signed by a user's Digi-ID-compatible wallet.

Features

• Generates Digi-ID URIs according to the specification.
• Verifies Digi-ID callback signatures and data.
• Verifies signatures from all standard DigiByte address types (Legacy, SegWit P2SH, Native SegWit/Bech32).
• Full TypeScript support with comprehensive type definitions.
• Modern ES modules support.
• Minimal dependencies, relying on standard cryptographic libraries.
• Comprehensive test coverage.
• Detailed error messages for debugging.

Installation

# Using npm
npm install digiid-ts

# Using yarn
yarn add digiid-ts

# Using pnpm
pnpm add digiid-ts

The package provides both ESM and UMD builds, with full TypeScript type definitions.

Requirements

• Node.js 16.0.0 or higher
• TypeScript 4.5 or higher (for TypeScript users)

Usage

Generating a Digi-ID URI

import { generateDigiIDUri, DigiIDError } from 'digiid-ts';

const options = {
  callbackUrl: 'https://your-site.com/auth/callback',
  // Optional parameters:
  nonce: 'custom-nonce', // Defaults to random UUID
  unsecure: false, // Defaults to false (requires HTTPS)
};

try {
  const digiidUri = generateDigiIDUri(options);
  console.log('Generated Digi-ID URI:', digiidUri);
  // Display this URI as a QR code for the user to scan
} catch (error) {
  if (error instanceof DigiIDError) {
    console.error('Failed to generate Digi-ID URI:', error.message);
  }
}

Verifying the Digi-ID Callback

import { verifyDigiIDCallback, DigiIDError, DigiIDCallbackData } from 'digiid-ts';

// In your Express route handler:
app.post('/auth/callback', async (req, res) => {
  const callbackData: DigiIDCallbackData = req.body; // { address, uri, signature }
  
  const verifyOptions = {
    expectedCallbackUrl: 'https://your-site.com/auth/callback',
    expectedNonce: 'your-stored-nonce', // The nonce you generated earlier
  };

  try {
    const verificationResult = await verifyDigiIDCallback(callbackData, verifyOptions);
    
    // Verification successful!
    console.log(`Successfully verified Digi-ID login for address: ${verificationResult.address}`);
    
    // Store the verified address in your session/database
    // Redirect to success page
    res.redirect('/dashboard');
  } catch (error) {
    if (error instanceof DigiIDError) {
      // Specific Digi-ID error (e.g., signature invalid, nonce mismatch, URL mismatch)
      console.error('Digi-ID verification failed:', error.message);
      res.status(400).json({ error: error.message });
    } else {
      // Unexpected error
      console.error('Unexpected error:', error);
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

API Reference

Core Functions

• generateDigiIDUri(options: DigiIDUriOptions): string
  • Generates a Digi-ID URI for QR code display.
• verifyDigiIDCallback(callbackData: DigiIDCallbackData, verifyOptions: DigiIDVerifyOptions): Promise<DigiIDVerificationResult>
  • Verifies the data received from the wallet callback. Resolves on success, throws DigiIDError on failure.

Type Definitions

• DigiIDUriOptions: Options for generateDigiIDUri.
• DigiIDCallbackData: Shape of data expected from the wallet callback.
• DigiIDVerifyOptions: Options for verifyDigiIDCallback.
• DigiIDVerificationResult: Shape of the success result from verifyDigiIDCallback.
• DigiIDError: Custom error class thrown on failures.

Development

Prerequisites

• Node.js 18+
• npm 9+

Setup

1. Clone the repository
2. Install dependencies: npm install
3. Run tests: npm test

Project Structure

• src/ - Source code
  • digiid.ts - Core implementation
  • types.ts - TypeScript type definitions
• test/ - Test files
• examples/ - Usage examples
• dist/ - Built files (generated)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.