Skip to content

README.md

Latest commit

 

History

History
209 lines (149 loc) · 5.02 KB

README.md

File metadata and controls

209 lines (149 loc) · 5.02 KB

TAP-WASM

Lightweight WebAssembly bindings for the Transaction Authorization Protocol (TAP), focusing on cryptographic operations that cannot be performed natively in JavaScript.

Features

  • Cryptographic Operations Only: Focused on signing/verification that requires WASM
  • DIDComm v2 Support: Pack and unpack messages with JWS signatures
  • Multiple Key Types: Ed25519, P-256, and secp256k1 support
  • TypeScript Ready: Full type definitions included
  • Optimized Size: Minimal API surface for smaller bundles (~272KB gzipped)

Purpose

The TAP WASM module provides a minimal set of cryptographic operations for TAP messages:

  • Key Management: Generate, import, and export cryptographic keys
  • Message Signing: Pack messages with DIDComm v2 JWS signatures
  • Signature Verification: Unpack and verify signed messages

Message creation, structuring, and business logic are handled by the TypeScript SDK (@taprsvp/agent), keeping the WASM bundle focused and small.

Installation

For most users, install the TypeScript SDK which includes the WASM module:

npm install @taprsvp/agent

For direct WASM usage (advanced):

npm install tap-wasm

Basic Usage

TypeScript/JavaScript (Recommended)

Use the TypeScript SDK for a complete TAP implementation:

import { TapAgent } from '@taprsvp/agent';

async function main() {
  // Create agent with auto-generated keys
  const agent = await TapAgent.create({ keyType: 'Ed25519' });
  console.log('Agent DID:', agent.did);
  
  // Create message in TypeScript
  const message = await agent.createMessage('Transfer', {
    amount: '100.00',
    asset: 'USD',
    originator: { '@id': agent.did },
    beneficiary: { '@id': 'did:key:recipient' }
  });
  
  // Use WASM for cryptographic operations
  const packed = await agent.pack(message);  // Signs with WASM
  const unpacked = await agent.unpack(packed.message);  // Verifies with WASM
}

main();

Direct WASM Usage (Advanced)

For direct WASM usage without the TypeScript SDK:

import init, { WasmTapAgent } from 'tap-wasm';

async function main() {
  // Initialize WASM module
  await init();
  
  // Create agent
  const agent = new WasmTapAgent({});
  console.log('DID:', agent.get_did());
  
  // Export keys
  const privateKey = agent.exportPrivateKey();
  const publicKey = agent.exportPublicKey();
  
  // Pack a message (must be properly formatted)
  const message = {
    id: 'msg_123',
    type: 'https://tap.rsvp/schema/1.0#Transfer',
    from: agent.get_did(),
    to: ['did:key:recipient'],
    body: { /* TAP message body */ }
  };
  
  const packed = await agent.packMessage(message);
  const unpacked = await agent.unpackMessage(packed.message);
}

main();

API Reference

WasmTapAgent

The core WASM agent providing cryptographic operations.

Creation

// Create with auto-generated keys
const agent = new WasmTapAgent({
  nickname: 'optional-nickname',
  debug: false
});

// Create from existing private key
const agent = await WasmTapAgent.fromPrivateKey(
  privateKeyHex,  // Hex-encoded private key
  'Ed25519'       // Key type: 'Ed25519', 'P256', or 'Secp256k1'
);

Key Management

// Get agent's DID
const did = agent.get_did();

// Export keys
const privateKey = agent.exportPrivateKey();  // Hex string
const publicKey = agent.exportPublicKey();    // Hex string

// Get nickname
const nickname = agent.nickname();  // Optional string

Message Operations

// Pack (sign) a message
const packedResult = await agent.packMessage(message);
// Returns: { message: string, metadata: {...} }

// Unpack (verify) a message
const unpacked = await agent.unpackMessage(
  packedMessage,      // JWS string
  expectedType        // Optional: expected message type for validation
);
// Returns: { id, type, from, to, body, ... }

Utility Functions

import { generate_uuid_v4, generatePrivateKey } from 'tap-wasm';

// Generate UUID
const uuid = generate_uuid_v4();

// Generate private key
const privateKey = generatePrivateKey('Ed25519');  // Returns hex string

Key Types

Supported cryptographic key types:

  • Ed25519: Fast, secure, recommended for most use cases
  • P256: NIST standard, good compatibility
  • Secp256k1: Bitcoin/Ethereum compatible

Integration with TypeScript SDK

The TypeScript SDK (@taprsvp/agent) provides:

  • Message creation and structuring
  • Type safety and validation
  • DID resolution
  • Business logic

While WASM provides:

  • Cryptographic key operations
  • Message signing (pack)
  • Signature verification (unpack)

This separation keeps the WASM bundle small while providing a complete TAP implementation.

Building from Source

# Clone repository
git clone https://github.com/notabene-id/tap-rs.git
cd tap-rs/tap-wasm

# Build WASM
wasm-pack build --target web

# Output in pkg/ directory

Performance

  • WASM module: ~272KB gzipped
  • Pack operation: < 5ms typical
  • Unpack operation: < 5ms typical
  • Key generation: < 2ms typical

License

MIT License