SchemaPin Reference Implementation Plan

1. System Architecture Overview

The SchemaPin reference implementation will demonstrate cross-language interoperability with both Python and JavaScript implementations, showcasing the complete workflow from tool developer signing to client verification.

graph TB
    subgraph "Tool Developer Workflow"
        A[Tool Schema JSON] --> B[Schema Canonicalizer]
        B --> C[SHA-256 Hash]
        C --> D[ECDSA P-256 Signature]
        D --> E[Base64 Encoded Signature]
        F[Private Key] --> D
        G[Public Key] --> H[.well-known/schemapin.json]
    end
    
    subgraph "Client Verification Workflow"
        I[Fetch Schema + Signature] --> J[Discover Public Key]
        J --> K[Pin Key on First Use]
        K --> L[Canonicalize Schema]
        L --> M[SHA-256 Hash]
        M --> N[Verify ECDSA Signature]
        N --> O{Valid?}
        O -->|Yes| P[Use Tool]
        O -->|No| Q[Reject & Alert]
    end
    
    subgraph "Core Components"
        R[SchemaPin Core Library]
        S[Key Management]
        T[Signature Utilities]
        U[HTTP Client]
        V[Storage Layer]
    end

Loading

2. Core Components Architecture

classDiagram
    class SchemaPinCore {
        +canonicalize_schema(schema: dict) str
        +hash_canonical(canonical: str) bytes
        +sign_hash(hash: bytes, private_key) str
        +verify_signature(hash: bytes, signature: str, public_key) bool
    }
    
    class KeyManager {
        +generate_keypair() tuple
        +load_private_key(path: str) PrivateKey
        +load_public_key(pem: str) PublicKey
        +export_public_key_pem(key) str
    }
    
    class SignatureManager {
        +sign_schema(schema: dict, private_key) str
        +verify_schema(schema: dict, signature: str, public_key) bool
    }
    
    class PublicKeyDiscovery {
        +fetch_well_known(domain: str) dict
        +construct_well_known_url(domain: str) str
        +validate_well_known_response(response: dict) bool
    }
    
    class KeyPinning {
        +pin_key(tool_id: str, public_key: str)
        +get_pinned_key(tool_id: str) str
        +is_key_pinned(tool_id: str) bool
        +list_pinned_keys() dict
    }
    
    SchemaPinCore --> KeyManager
    SchemaPinCore --> SignatureManager
    SignatureManager --> PublicKeyDiscovery
    SignatureManager --> KeyPinning

Loading

3. Technology Stack

Python Implementation

Core Crypto: cryptography library (ECDSA P-256, SHA-256)
HTTP Client: requests for .well-known discovery
JSON: Built-in json module with custom canonicalization
Storage: sqlite3 for key pinning persistence
Testing: pytest with crypto test vectors

JavaScript Implementation

Core Crypto: Node.js crypto module (ECDSA P-256, SHA-256)
HTTP Client: fetch API or axios for .well-known discovery
JSON: Built-in JSON with custom canonicalization
Storage: sqlite3 or JSON file for key pinning
Testing: jest with matching test vectors

Shared Components

Test Vectors: Cross-language compatibility test suite
Example Schemas: Sample tool schemas for testing
Documentation: API docs and usage examples

4. Project Structure

SchemaPin/
├── README.md
├── TECHNICAL_SPECIFICATION.md
├── IMPLEMENTATION_PLAN.md
├── LICENSE
├── .gitignore
├── docs/
│   ├── api-reference.md
│   ├── examples.md
│   └── security-considerations.md
├── python/
│   ├── schemapin/
│   │   ├── __init__.py
│   │   ├── core.py
│   │   ├── crypto.py
│   │   ├── discovery.py
│   │   ├── pinning.py
│   │   └── utils.py
│   ├── examples/
│   │   ├── tool_developer.py
│   │   ├── client_verification.py
│   │   └── sample_schemas/
│   ├── tests/
│   │   ├── test_core.py
│   │   ├── test_crypto.py
│   │   └── test_vectors.py
│   ├── requirements.txt
│   └── setup.py
├── javascript/
│   ├── src/
│   │   ├── index.js
│   │   ├── core.js
│   │   ├── crypto.js
│   │   ├── discovery.js
│   │   ├── pinning.js
│   │   └── utils.js
│   ├── examples/
│   │   ├── tool-developer.js
│   │   ├── client-verification.js
│   │   └── sample-schemas/
│   ├── tests/
│   │   ├── core.test.js
│   │   ├── crypto.test.js
│   │   └── test-vectors.test.js
│   ├── package.json
│   └── package-lock.json
├── test-vectors/
│   ├── schemas.json
│   ├── signatures.json
│   └── keys.json
├── examples/
│   ├── well-known-server/
│   │   ├── server.py
│   │   └── static/.well-known/schemapin.json
│   └── integration-demo/
│       ├── demo-tool-server.py
│       └── demo-client.py
└── tools/
    ├── keygen.py
    ├── schema-signer.py
    └── verify-schema.py

5. Implementation Phases

Phase 1: Core Cryptographic Foundation (Week 1)

Python Implementation:

Schema canonicalization engine
SHA-256 hashing utilities
ECDSA P-256 key generation/management
Signature creation and verification
Comprehensive test suite with known test vectors

JavaScript Implementation:

Mirror Python functionality using Node.js crypto
Ensure identical canonicalization results
Cross-language test vector validation

Phase 2: Public Key Discovery & Pinning (Week 2)

Both Languages:

.well-known URI construction and fetching
Public key discovery client
Key pinning storage mechanism
First-use key pinning workflow
Error handling for network failures

Phase 3: Integration Layer (Week 3)

High-Level APIs:

Tool developer signing workflow
Client verification workflow
Configuration management
Logging and debugging utilities

Example Applications:

Command-line tool signer
Schema verification utility
Sample .well-known server

Phase 4: Documentation & Examples (Week 4)

Documentation:

API reference documentation
Security best practices guide
Integration examples

Demo Applications:

Complete tool developer workflow
Client verification demonstration
Cross-language interoperability demo

6. Key Technical Challenges & Mitigation

Challenge 1: Schema Canonicalization Consistency

Risk: Different JSON serialization across languages Mitigation:

Implement strict canonicalization rules
Extensive cross-language test vectors
Reference canonical strings for validation

Challenge 2: Cryptographic Compatibility

Risk: ECDSA signature differences between implementations Mitigation:

Use standard P-256 curve parameters
Test with known signature vectors
Validate against OpenSSL reference

Challenge 3: Key Pinning Security

Risk: TOFU (Trust On First Use) vulnerabilities Mitigation:

Clear user prompts for key pinning
Key fingerprint display
Audit logging for key changes

Challenge 4: Network Security

Risk: .well-known endpoint compromise Mitigation:

HTTPS enforcement
Certificate pinning recommendations
Fallback to cached keys

7. Testing Strategy

Unit Testing

Individual component testing
Cryptographic primitive validation
Error condition handling

Integration Testing

End-to-end workflow testing
Cross-language compatibility
Network failure scenarios

Security Testing

Known attack vector validation
Malformed input handling
Timing attack resistance

Performance Testing

Large schema handling
Signature verification speed
Memory usage profiling

8. Success Criteria

Functional Completeness: Both Python and JavaScript implementations pass identical test suites
Cross-Language Compatibility: Signatures created in one language verify correctly in the other
Security Compliance: Implementation follows all TECHNICAL_SPECIFICATION.md requirements
Usability: Clear examples demonstrate both developer and client workflows
Documentation: Comprehensive guides enable third-party integration

9. Next Steps

This implementation plan provides a comprehensive roadmap for creating a reference SchemaPin implementation that demonstrates the protocol's security benefits while maintaining simplicity and cross-language compatibility. The phased approach ensures steady progress while allowing for iterative testing and refinement.

The reference implementation will serve as:

A proof-of-concept for the SchemaPin protocol
A foundation for production implementations
Educational material for developers
A test suite for protocol compliance

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!