CryptoGuard SDK

Multi-platform binary transparency verification SDK for Chrome extensions and Node.js servers

A production-ready TypeScript SDK that enables binary transparency verification through cryptographic hash comparison against blockchain-stored references. Built for developers who need reliable, real-time verification across multiple platforms.

🚀 Quick Start

Extension Platform

import { CryptoGuardSDKFactory, VerificationEvent } from 'crptg';

// Create and initialize scanner
const scanner = CryptoGuardSDKFactory.create({ platform: 'extension' });
await scanner.initialize();

// Listen for verification events
scanner.on(VerificationEvent.VERIFICATION_COMPLETED, ({ result }) => {
  console.log('✅ Verified:', result.url);
});

// Automatic verification happens in background via webRequest
// Manual verification also available:
const result = await scanner.verifyResource('https://example.wal.app/app.js');

Server Platform

import { CryptoGuardSDKFactory } from 'crptg';
import { createHash } from 'crypto';

// Create and initialize scanner
const scanner = CryptoGuardSDKFactory.create({ platform: 'server' });
await scanner.initialize();

// Compute hash and verify
const fileContent = fs.readFileSync('./app.js');
const hash = createHash('sha256').update(fileContent).digest('hex');

const result = await scanner.verifyResource({
  url: 'https://example.com/app.js',
  hash: hash
});

console.log('Status:', result.status); // VERIFIED | FAILED | ERROR

📦 Installation

npm install crptg

Requirements:

• Node.js 18.0.0+
• TypeScript 5.0+ (if using TypeScript)
• Chrome 88+ (for extensions)

🏗️ Features

Multi-Platform Support

• Extension: Automatic verification via chrome.webRequest + manual verification
• Server: Manual verification with user-provided hash

Dual Registry System

• Walrus Registry: *.wal.app domains on Sui mainnet
• CryptoGuard Registry: All other domains on Sui testnet

Production Ready

• ✅ TypeScript native with full type safety
• ✅ Event-driven architecture
• ✅ Zero configuration (hardcoded security)
• ✅ Binary and text file support
• ✅ Comprehensive error handling

📖 Documentation

Quick Links

• Complete Architecture Guide - Comprehensive implementation guide with:
  • Detailed architecture diagrams
  • Design patterns explained
  • Network configuration
  • API reference
  • Implementation examples
  • Technical deep dives

Key Concepts

Factory Pattern:

const scanner = CryptoGuardSDKFactory.create({
  platform: 'extension' | 'server'
});

Verification Events:

• VERIFICATION_STARTED - Verification begins
• REGISTRY_FOUND - Domain found in registry
• RESOURCE_COMPLETED - Individual resource verified
• VERIFICATION_COMPLETED - All resources verified successfully
• VERIFICATION_FAILED - Verification failed (hash mismatch)
• ERROR - Technical error occurred

Verification Results:

interface SiteVerificationResult {
  domain: string;
  url: string;
  status: VerificationStatus;
  registryType?: RegistryType;
  resources: ResourceVerificationResult[];
  processingTime: number;
  requestId: string;
}

🎯 Use Cases

Chrome Extension Security

Automatically verify all resources loaded by websites to detect tampering:

const scanner = CryptoGuardSDKFactory.create({ platform: 'extension' });
await scanner.initialize();

// All HTTPS requests automatically verified in background
// Users see badge indicator: ✓ (verified) or ✗ (failed)

Server-Side Verification

Verify served static assets before deployment or at runtime:

const scanner = CryptoGuardSDKFactory.create({ platform: 'server' });
await scanner.initialize();

// Middleware to verify all static assets
app.use(async (req, res, next) => {
  const hash = computeFileHash(req.path);
  const result = await scanner.verifyResource({
    url: `https://example.com${req.path}`,
    hash
  });

  if (result.status === 'FAILED') {
    return res.status(403).send('Integrity check failed');
  }
  next();
});

CI/CD Pipeline Integration

Verify build artifacts before deployment:

const scanner = CryptoGuardSDKFactory.create({ platform: 'server' });
await scanner.initialize();

// Verify all built assets
for (const file of buildFiles) {
  const hash = computeHash(file.content);
  const result = await scanner.verifyResource({
    url: `https://cdn.example.com/${file.path}`,
    hash
  });

  if (result.status !== 'VERIFIED') {
    throw new Error(`Build verification failed: ${file.path}`);
  }
}

🔧 Configuration

Extension Setup

1. Update manifest.json:

{
  "manifest_version": 3,
  "permissions": ["webRequest"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "service-worker.js",
    "type": "module"
  }
}

2. Build Configuration:

{
  "compilerOptions": {
    "module": "esnext",
    "target": "es2020",
    "types": ["chrome"]
  }
}

Server Setup

1. Import SDK:

import { CryptoGuardSDKFactory } from 'crptg';

2. Initialize Once:

const scanner = CryptoGuardSDKFactory.create({ platform: 'server' });
await scanner.initialize();
// Reuse scanner instance for all verifications

🌐 Network Architecture

The SDK automatically selects the correct Sui network based on domain:

| Domain Pattern | Registry Type | Sui Network | Why | |----------------|---------------|-------------|-----| | *.wal.app | Walrus | Mainnet | Walrus sites deployed on mainnet | | All others | CryptoGuard | Testnet | CryptoGuard registry on testnet |

No user configuration needed - network selection is hardcoded for security.

📊 API Overview

Factory API

CryptoGuardSDKFactory.create(config: SDKFactoryConfig): CryptoGuardScanner

Scanner API

// Initialize
await scanner.initialize(): Promise<void>

// Verify resource (platform-specific overloads)
await scanner.verifyResource(url: string): Promise<SiteVerificationResult>
await scanner.verifyResource(params: { url: string; hash: string }): Promise<SiteVerificationResult>

// Event listeners
scanner.on(event: VerificationEvent, callback: Function): void

// Get statistics
scanner.getStatistics(): ScannerStatistics

Type Definitions

type SDKPlatform = 'extension' | 'server';

enum VerificationStatus {
  VERIFIED = 'VERIFIED',
  FAILED = 'FAILED',
  ERROR = 'ERROR',
  IGNORED = 'IGNORED',
  PARTIAL = 'PARTIAL'
}

enum RegistryType {
  WALRUS = 'walrus',
  CRYPTOGUARD = 'cryptoguard'
}

See ARCHITECTURE.md for complete API reference.

🐛 Troubleshooting

Common Issues

Extension won't load:

• Verify manifest.json has correct permissions
• Check Service Worker console for errors
• Ensure loaded as "unpacked" extension

No verification events:

• Check chrome.webRequest permission granted
• Verify host_permissions includes <all_urls>
• Visit HTTPS sites (HTTP not supported)

Hash mismatch errors:

• Ensure using SDK v0.2.1+ (binary file bug fixed)
• Check if resource is registered in the correct registry
• Verify network connectivity to Sui RPC

Server platform errors:

• Ensure hash is SHA-256 (64 hex characters)
• Check hash computed from raw file bytes (not base64)
• Verify URL format matches registry entry exactly

🔐 Security

Design Principles

1. Hardcoded Configuration: No user-configurable endpoints or networks
2. Blockchain Verification: All expected hashes stored on-chain
3. Cryptographic Integrity: SHA-256 hash comparison
4. Zero Trust: Every resource verified independently

Hash Computation

// Critical: Use arrayBuffer() for correct binary handling
const response = await fetch(url);
const arrayBuffer = await response.arrayBuffer(); // ✅ Correct
const hash = await crypto.subtle.digest('SHA-256', arrayBuffer);

Never use response.text() - corrupts binary files (.wasm, .png, .ttf, etc.)

📝 Version History

v0.2.1 (Current)

• Critical Fix: Binary file hashing bug (use arrayBuffer() instead of text())
• Enhanced error logging with hash comparison

v0.2.0

• Multi-platform support (extension + server)
• Factory pattern implementation
• Strategy pattern for URL capture
• Dual network configuration
• Breaking changes from v0.1.x

v0.1.x

• Initial release
• Extension platform only
• Basic verification

See ARCHITECTURE.md for detailed version history.

🤝 Contributing

Contributions welcome! Please:

1. Read ARCHITECTURE.md to understand the design
2. Open an issue to discuss major changes
3. Follow existing code style and patterns
4. Add tests for new features
5. Update documentation

📄 License

MIT License - See LICENSE file for details

🔗 Links

• Repository: https://github.com/CommandOSSLabs/binary-transparency
• npm Package: https://www.npmjs.com/package/crptg
• Architecture Guide: ARCHITECTURE.md
• Sui Blockchain: https://sui.io
• Walrus Storage: https://walrus.site

💡 Support

• Issues: https://github.com/CommandOSSLabs/binary-transparency/issues
• Documentation: See ARCHITECTURE.md

Built with ❤️ by the CryptoGuard Team

Last Updated: October 2025 | Version 0.2.1