Knowe SDK

A TypeScript/JavaScript SDK for integrating with the Knowe identity verification service. This library provides easy-to-use methods for generating verification URLs, validating HMAC signatures, and looking up user information.

✅ Browser Compatible - Works in both Node.js and browser environments without polyfills!

Installation

npm install knowe

Quick Start

import { Knowe } from 'knowe';

// Initialize the Knowe client
const knowe = new Knowe(
  Date.now() + 3600000,           // Expiry date in unix timestamp, in this example, it will generate a time that expires in 1 hour
  'your-service-id',              // Service identifier from Knowe dashboard
  '[email protected]',          // Your user's email
  'https://yourapp.com/success',  // Redirect_success link on your web app
  'https://yourapp.com/fail',     // Redirect_fail link on your web app
  [{ key: 'plan', value: 'premium' }], // Metadata: Any extra data you want to add
  'your-api-key'                  // Secret API key from Knowe dashboard
);

// Generate a verification URL (now async!)
const userId = await knowe.getUserId();
const facialVerificationURL = await knowe.generateUrl(userId);
console.log('Verification URL:', facialVerificationURL);
//https://you.knowe.me/validate?<query params>
...
//For extra security, you can validate signature key (now async!)
const validateSignatureKey = await knowe.checkSignatureKey('the signature key', userId);
console.log(validateSignatureKey) //true or false

🚨 Breaking Changes in v1.0.1

Important: This version includes breaking changes to support browser environments without polyfills:

• generateUrl() is now async and returns Promise<string>
• checkSignatureKey() is now async and returns Promise<boolean>

Update your code accordingly:

// Before (v1.0.0)
const url = knowe.generateUrl(userId);
const isValid = knowe.checkSignatureKey(signature, userId);

// After (v1.0.1+) 
const url = await knowe.generateUrl(userId);
const isValid = await knowe.checkSignatureKey(signature, userId);

Constructor Parameters

new Knowe(
  expiry: number,              // Unix timestamp when the verification expires
  service_id: string,          // Your service identifier from Knowe dashboard
  email: string,               // Your user's email address
  redirect_success: string,    // URL to redirect after successful verification
  redirect_fail: string,       // URL to redirect after failed verification
  metadata: KnoweMetadata[],   // Additional key-value pairs
  apiKey: string               // Your secret API key from Knowe dashboard
)

KnoweMetadata Interface

interface KnoweMetadata {
  key: string;
  value: string;
}

API Methods

generateUrl(userId: string): Promise<string>

Generates a verification URL for the specified user.

const verificationUrl = await knowe.generateUrl('user123');
// Returns: https://you.knowe.me/validate?expiry=...&signature=...

checkSignatureKey(payloadSignature: string, userId: string): Promise<boolean>

Validates signature against the expected signature for the given user.

const isValid = await knowe.checkSignatureKey(receivedSignature, 'user123');
if (isValid) {
  console.log('Signature is valid');
} else {
  console.log('Invalid signature');
}

getUserId(): Promise<string>

Looks up a user ID from the Knowe service using service ID and email.

try {
  const userId = await knowe.getUserId();
  console.log('User ID:', userId);
} catch (error) {
  console.error('Lookup failed:', error);
}

Complete Example

import { Knowe, KnoweMetadata } from 'knowe';

async function verifyUser() {
  // Setup metadata
  const metadata: KnoweMetadata[] = [
    { key: 'plan', value: 'premium' },
    { key: 'department', value: 'engineering' }
  ];

  // Initialize Knowe client
  const knowe = new Knowe(
    Date.now() + 24 * 60 * 60 * 1000, // 24 hours from now
    'my-service-123',
    '[email protected]',
    'https://myapp.com/verification-success',
    'https://myapp.com/verification-failed',
    metadata,
    process.env.KNOWE_API_KEY || 'your-api-key'
  );

  try {
    // Look up existing user
    const userId = await knowe.getUserId();
    
    // Generate verification URL
    const verificationUrl = await knowe.generateUrl(userId);
    
    console.log('Send this URL to the user:', verificationUrl);
    
    // Later, when you receive a callback with signature
    const receivedSignature = 'signature-from-callback';
    const isValidSignature = await knowe.checkSignatureKey(receivedSignature, userId);
    
    if (isValidSignature) {
      console.log('User successfully verified!');
    } else {
      console.log('Verification failed - invalid signature');
    }
    
  } catch (error) {
    console.error('Error during verification process:', error);
  }
}

verifyUser();

Environment Variables

For security, store your API key in environment variables:

KNOWE_API_KEY=your-actual-api-key

const knowe = new Knowe(
  // ... other parameters
  process.env.KNOWE_API_KEY!
);

Error Handling

The SDK throws errors for various failure scenarios:

try {
  const userId = await knowe.getUserId();
} catch (error) {
  if (error instanceof Error) {
    console.error('Lookup failed:', error.message);
    // Handle specific error cases
    if (error.message.includes('404')) {
      console.log('User not found');
    } else if (error.message.includes('500')) {
      console.log('Server error, try again later');
    }
  }
}

TypeScript Support

This package includes full TypeScript definitions and works in both browser and Node.js environments. Import types as needed:

import { Knowe, KnoweMetadata } from 'knowe';

const metadata: KnoweMetadata[] = [
  { key: 'role', value: 'admin' }
];

Browser Compatibility

This library now works natively in modern browsers without requiring polyfills! It uses:

• Web Crypto API for HMAC operations in browsers
• Node.js crypto module as fallback for server environments
• Fetch API for HTTP requests (supported in all modern browsers)

Supported Browsers

• Chrome 37+
• Firefox 34+
• Safari 7+
• Edge 79+
• iOS Safari 8+
• Android Chrome 37+

Ionic Angular Usage

No polyfills required! Simply install and use:

// In your Ionic Angular service or component
import { Knowe } from 'knowe';

@Injectable({
  providedIn: 'root'
})
export class KnoweService {
  private knowe: Knowe;

  constructor() {
    this.knowe = new Knowe(
      Date.now() + 3600000,
      'your-service-id',
      '[email protected]',
      'https://yourapp.com/success',
      'https://yourapp.com/fail',
      [],
      'your-api-key'
    );
  }

  async generateVerificationUrl(userId: string): Promise<string> {
    return await this.knowe.generateUrl(userId);
  }
}

License

MIT

Support

For issues and questions, please visit the GitHub repository or contact support.