Skip to content

README.md

Latest commit

 

History

History
208 lines (155 loc) · 5.9 KB

README.md

File metadata and controls

208 lines (155 loc) · 5.9 KB

SchemaPin JavaScript Implementation

A JavaScript/Node.js implementation of the SchemaPin protocol for cryptographic schema integrity verification of AI tools.

Overview

SchemaPin provides cryptographic verification of AI tool schemas using ECDSA P-256 signatures and Trust-On-First-Use (TOFU) key pinning. This JavaScript implementation mirrors the functionality of the Python reference implementation.

Features

  • ECDSA P-256 Cryptography: Industry-standard elliptic curve signatures
  • Schema Canonicalization: Deterministic JSON serialization for consistent hashing
  • Public Key Discovery: Automatic retrieval from .well-known/schemapin.json endpoints
  • Key Pinning: Trust-On-First-Use security model with persistent storage
  • Cross-Platform: Works in Node.js environments
  • Zero Dependencies: Uses only Node.js built-in modules

Installation

From npm (Recommended)

# Install latest stable version
npm install schemapin

# Install globally for CLI usage (if CLI tools are added)
npm install -g schemapin

From Source (Development)

# Clone repository and install dependencies
git clone https://github.com/thirdkey/schemapin.git
cd schemapin/javascript
npm install

Quick Start

Tool Developer Workflow

import { KeyManager, SchemaSigningWorkflow, createWellKnownResponse } from 'schemapin';

// 1. Generate key pair
const { privateKey, publicKey } = KeyManager.generateKeypair();

// 2. Sign your tool schema
const schema = {
    name: "calculate_sum",
    description: "Calculates the sum of two numbers",
    parameters: {
        type: "object",
        properties: {
            a: { type: "number", description: "First number" },
            b: { type: "number", description: "Second number" }
        },
        required: ["a", "b"]
    }
};

const signingWorkflow = new SchemaSigningWorkflow(privateKey);
const signature = signingWorkflow.signSchema(schema);

// 3. Create .well-known response
const wellKnownResponse = createWellKnownResponse(
    publicKey,
    "Your Organization",
    "contact@yourorg.com"
);

// Host wellKnownResponse at https://yourdomain.com/.well-known/schemapin.json

Client Verification Workflow

import { SchemaVerificationWorkflow } from 'schemapin';

const verificationWorkflow = new SchemaVerificationWorkflow();

// Verify schema with automatic key pinning
const result = await verificationWorkflow.verifySchema(
    schema,
    signature,
    "yourdomain.com/calculate_sum",
    "yourdomain.com",
    true // auto-pin on first use
);

if (result.valid) {
    console.log("✅ Schema signature is valid");
    if (result.first_use) {
        console.log("🔑 Key pinned for future use");
    }
} else {
    console.log("❌ Schema signature is invalid");
    console.log("Error:", result.error);
}

API Reference

Core Classes

SchemaPinCore

  • canonicalizeSchema(schema) - Convert schema to canonical string format
  • hashCanonical(canonical) - SHA-256 hash of canonical string
  • canonicalizeAndHash(schema) - Combined canonicalization and hashing

KeyManager

  • generateKeypair() - Generate new ECDSA P-256 key pair
  • exportPrivateKeyPem(privateKey) - Export private key to PEM format
  • exportPublicKeyPem(publicKey) - Export public key to PEM format
  • loadPrivateKeyPem(pemData) - Load private key from PEM
  • loadPublicKeyPem(pemData) - Load public key from PEM

SignatureManager

  • signHash(hashBytes, privateKey) - Sign hash with private key
  • verifySignature(hashBytes, signature, publicKey) - Verify signature
  • signSchemaHash(schemaHash, privateKey) - Sign schema hash
  • verifySchemaSignature(schemaHash, signature, publicKey) - Verify schema signature

PublicKeyDiscovery

  • fetchWellKnown(domain) - Fetch .well-known/schemapin.json
  • getPublicKeyPem(domain) - Get public key from domain
  • getDeveloperInfo(domain) - Get developer information

KeyPinning

  • pinKey(toolId, publicKeyPem, domain, developerName) - Pin public key
  • getPinnedKey(toolId) - Get pinned key for tool
  • isKeyPinned(toolId) - Check if key is pinned
  • listPinnedKeys() - List all pinned keys
  • removePinnedKey(toolId) - Remove pinned key

High-Level Workflows

SchemaSigningWorkflow

const workflow = new SchemaSigningWorkflow(privateKeyPem);
const signature = workflow.signSchema(schema);

SchemaVerificationWorkflow

const workflow = new SchemaVerificationWorkflow();
const result = await workflow.verifySchema(schema, signature, toolId, domain, autoPin);

Examples

Run the included examples:

# Tool developer workflow
node examples/developer.js

# Client verification workflow  
node examples/client.js

Testing

npm test

Security Considerations

  • Private Key Security: Store private keys securely and never expose them
  • HTTPS Required: Always use HTTPS for .well-known endpoint discovery
  • Key Pinning: Review pinned keys periodically and verify authenticity
  • Signature Verification: Always verify signatures before using tool schemas

Cross-Language Compatibility

This JavaScript implementation is designed to be fully compatible with the Python reference implementation:

  • Identical schema canonicalization results
  • Compatible ECDSA P-256 signatures
  • Same .well-known endpoint format
  • Interoperable key formats (PEM)

Node.js Version Support

  • Node.js 18.0.0 or higher required
  • Uses built-in crypto module for cryptographic operations
  • ES modules (import/export) syntax

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

Support

For issues and questions:

  • GitHub Issues: SchemaPin Repository
  • Documentation: See TECHNICAL_SPECIFICATION.md
  • Examples: Check the examples/ directory