A modern TypeScript implementation of the DigiID authentication protocol.
npm install digiid-tsA 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.
* 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.
``bashUsing npm
npm install digiid-ts
The package provides both ESM and UMD builds, with full TypeScript type definitions.
$3
- Node.js 16.0.0 or higher
- TypeScript 4.5 or higher (for TypeScript users)Usage
$3
`typescript
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);
}
}
`$3
`typescript
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
$3
*
generateDigiIDUri(options: DigiIDUriOptions): string
* Generates a Digi-ID URI for QR code display.
* verifyDigiIDCallback(callbackData: DigiIDCallbackData, verifyOptions: DigiIDVerifyOptions): Promise
* Verifies the data received from the wallet callback. Resolves on success, throws DigiIDError on failure.$3
*
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
$3
* Node.js 18+
* npm 9+
$3
1. Clone the repository
2. Install dependencies:
npm install
3. Run tests: npm test$3
*
src/ - Source code
* digiid.ts - Core implementation
* types.ts - TypeScript type definitions
* test/ - Test files
* examples/ - Usage examples
* dist/` - Built files (generated)MIT
Contributions are welcome! Please feel free to submit a Pull Request.