schemapin

Category: Tools & Productivity | Uploader: ThirdKeyAI | Downloads: 0 | Version: v1.0（Latest）

Cryptographic tool schema verification to prevent MCP Rug Pull attacks — ECDSA P-256 signing, SHA-256 hashing, TOFU key pinning, and .well-known discovery

Changelog: Source: GitHub https://github.com/ThirdKeyAI/SchemaPin

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 docs.yml 745 B
  - 📄 README.md 5.9 KB
  - 📄 release-combined.yml 13.2 KB
  - 📄 release-crates.yml 8.2 KB
  - 📄 release-go.yml 6.7 KB
  - 📄 release-npm.yml 4.7 KB
  - 📄 release-pypi.yml 7.1 KB
📁 docs/
- 📄 api-reference.md 10.8 KB
- 📄 deployment.md 7.3 KB
- 📄 getting-started.md 7.8 KB
- 📄 index.md 3.6 KB
- 📄 skill-signing.md 8.8 KB
- 📄 troubleshooting.md 8.8 KB
- 📄 trust-bundles.md 8.4 KB
📁 go/
- 📁 cmd/
  - 📁 schemapin-keygen/
    
    📄 main.go 6.5 KB
  - 📁 schemapin-sign/
    
    📄 main.go 11.7 KB
  - 📁 schemapin-verify/
    
    📄 main.go 14.6 KB
- 📁 examples/
  - 📁 client/
    
    📄 demo_private_key.pem 241 B
    
    📄 demo_schema_signed.json 543 B
    
    📄 demo_well_known.json 319 B
    
    📄 main.go 9.7 KB
  - 📁 cross-language-demo/
    
    📄 main.go 9.1 KB
  - 📁 developer/
    
    📄 demo_private_key.pem 241 B
    
    📄 demo_schema_signed.json 543 B
    
    📄 demo_well_known.json 319 B
    
    📄 main.go 4.0 KB
  - 📁 interactive-demo/
    
    📄 main.go 10.6 KB
- 📁 internal/
  - 📁 version/
    
    📄 version.go 259 B
- 📁 pkg/
  - 📁 bundle/
    
    📄 bundle.go 3.2 KB
    
    📄 bundle_test.go 4.3 KB
  - 📁 core/
    
    📄 core.go 2.4 KB
    
    📄 core_test.go 9.0 KB
  - 📁 crypto/
    
    📄 cross_compatibility_test.go 7.8 KB
    
    📄 crypto.go 5.3 KB
    
    📄 crypto_test.go 10.6 KB
  - 📁 discovery/
    
    📄 discovery.go 7.5 KB
    
    📄 discovery_test.go 11.0 KB
  - 📁 interactive/
    
    📄 interactive.go 15.0 KB
    
    📄 interactive_test.go 12.5 KB
  - 📁 pinning/
    
    📄 pinning.go 15.3 KB
    
    📄 pinning_test.go 17.7 KB
  - 📁 resolver/
    
    📄 resolver.go 5.4 KB
    
    📄 resolver_test.go 6.1 KB
  - 📁 revocation/
    
    📄 revocation.go 3.3 KB
    
    📄 revocation_test.go 4.6 KB
  - 📁 skill/
    
    📄 skill.go 13.2 KB
    
    📄 skill_test.go 17.5 KB
  - 📁 utils/
    
    📄 utils.go 14.3 KB
    
    📄 utils_test.go 18.1 KB
  - 📁 verification/
    
    📄 verification.go 7.2 KB
    
    📄 verification_test.go 10.2 KB
  - 📄 integration_test.go 7.0 KB
- 📁 tests/
  - 📄 integration_test.go 12.1 KB
- 📄 .gitignore 556 B
- 📄 demo_signed.json 310 B
- 📄 go.mod 270 B
- 📄 go.sum 1.7 KB
- 📄 Makefile 8.9 KB
- 📄 README.md 13.3 KB
- 📄 schemapin.json 328 B
- 📄 schemapin_private.pem 241 B
- 📄 schemapin_public.pem 178 B
📁 integration_demo/
- 📁 sample_schemas/
  - 📄 api_endpoint.json 2.3 KB
  - 📄 complex_nested.json 2.5 KB
  - 📄 mcp_tool.json 649 B
- 📄 cross_language_test.py 23.1 KB
- 📄 demo_scenario.js 17.3 KB
- 📄 demo_scenario.py 22.8 KB
- 📄 demo_scenario_go.py 19.1 KB
- 📄 package.json 1.2 KB
- 📄 README.md 6.4 KB
📁 javascript/
- 📁 examples/
  - 📄 client.js 6.6 KB
  - 📄 developer.js 3.3 KB
  - 📄 interactive-pinning-demo.js 14.8 KB
- 📁 src/
  - 📄 bundle.js 1.8 KB
  - 📄 core.js 1.8 KB
  - 📄 crypto.js 4.4 KB
  - 📄 discovery.js 5.5 KB
  - 📄 index.js 1.5 KB
  - 📄 interactive.js 15.5 KB
  - 📄 pinning.js 15.0 KB
  - 📄 resolver.js 3.7 KB
  - 📄 revocation.js 2.9 KB
  - 📄 skill.js 12.8 KB
  - 📄 utils.js 6.1 KB
  - 📄 verification.js 6.7 KB
- 📁 tests/
  - 📄 bundle.test.js 3.4 KB
  - 📄 core.test.js 3.0 KB
  - 📄 cross-compatibility.test.js 4.2 KB
  - 📄 crypto.test.js 6.6 KB
  - 📄 interactive.test.js 12.5 KB
  - 📄 resolver.test.js 5.8 KB
  - 📄 revocation.test.js 6.4 KB
  - 📄 skill.test.js 21.5 KB
  - 📄 standalone-revocation.test.js 4.2 KB
  - 📄 verification.test.js 9.9 KB
- 📄 .npmignore 1.3 KB
- 📄 demo_private_key.pem 241 B
- 📄 demo_schema_signed.json 543 B
- 📄 demo_well_known.json 501 B
- 📄 eslint.config.js 744 B
- 📄 package-lock.json 52.5 KB
- 📄 package.json 3.2 KB
- 📄 README.md 5.9 KB
📁 python/
- 📁 examples/
  - 📄 cli_usage_examples.py 12.0 KB
  - 📄 client_verification.py 6.3 KB
  - 📄 demo_private_key.pem 241 B
  - 📄 demo_schema_signed.json 539 B
  - 📄 demo_well_known.json 502 B
  - 📄 interactive_pinning_demo.py 10.1 KB
  - 📄 key_revocation_demo.py 6.6 KB
  - 📄 tool_developer.py 3.3 KB
- 📁 schemapin/
  - 📄 __init__.py 2.3 KB
  - 📄 bundle.py 2.4 KB
  - 📄 core.py 1.5 KB
  - 📄 crypto.py 5.7 KB
  - 📄 discovery.py 5.1 KB
  - 📄 interactive.py 13.6 KB
  - 📄 pinning.py 16.1 KB
  - 📄 resolver.py 4.6 KB
  - 📄 revocation.py 4.0 KB
  - 📄 skill.py 12.7 KB
  - 📄 utils.py 6.0 KB
  - 📄 verification.py 7.9 KB
- 📁 tests/
  - 📄 test_bundle.py 4.5 KB
  - 📄 test_cli_tools.py 14.8 KB
  - 📄 test_core.py 3.0 KB
  - 📄 test_crypto.py 6.2 KB
  - 📄 test_interactive_pinning.py 12.2 KB
  - 📄 test_resolver.py 6.9 KB
  - 📄 test_revocation.py 7.0 KB
  - 📄 test_skill.py 21.4 KB
  - 📄 test_standalone_revocation.py 5.8 KB
  - 📄 test_verification.py 11.4 KB
- 📁 tools/
  - 📄 __init__.py 58 B
  - 📄 keygen.py 8.2 KB
  - 📄 schema_signer.py 11.4 KB
  - 📄 verify_schema.py 14.9 KB
- 📄 .bandit 61 B
- 📄 CHANGELOG.md 18.2 KB
- 📄 MANIFEST.in 1007 B
- 📄 pyproject.toml 3.3 KB
- 📄 README.md 8.1 KB
- 📄 requirements.txt 77 B
- 📄 setup.cfg 2.1 KB
- 📄 setup.py 1.8 KB
- 📄 TECHNICAL_SPECIFICATION.md 20.2 KB
📁 rust/
- 📁 src/
  - 📁 types/
    
    📄 bundle.rs 3.9 KB
    
    📄 discovery.rs 2.6 KB
    
    📄 mod.rs 72 B
    
    📄 pinning.rs 1.8 KB
    
    📄 revocation.rs 2.6 KB
  - 📄 canonicalize.rs 3.9 KB
  - 📄 core.rs 1.7 KB
  - 📄 crypto.rs 11.5 KB
  - 📄 discovery.rs 5.1 KB
  - 📄 error.rs 3.0 KB
  - 📄 lib.rs 2.8 KB
  - 📄 main.rs 63 B
  - 📄 pinning.rs 7.8 KB
  - 📄 resolver.rs 12.9 KB
  - 📄 revocation.rs 5.3 KB
  - 📄 skill.rs 29.1 KB
  - 📄 verification.rs 16.3 KB
- 📄 .gitignore 7 B
- 📄 Cargo.lock 48.7 KB
- 📄 Cargo.toml 1.2 KB
- 📄 README.md 6.2 KB
📁 scripts/
- 📄 build_packages.py 13.1 KB
- 📄 publish_javascript.sh 9.0 KB
- 📄 publish_python.py 11.5 KB
- 📄 test_packages.py 24.1 KB
📁 server/
- 📄 config.json 1.3 KB
- 📄 Dockerfile 881 B
- 📄 README.md 8.7 KB
- 📄 requirements.txt 215 B
- 📄 well_known_server.py 15.3 KB
📄 .gitignore 4.6 KB
📄 .npmrc.template 527 B
📄 .pypirc.template 389 B
📄 .schemapin.sig 543 B
📄 CHANGELOG.md 15.0 KB
📄 CODE_OF_CONDUCT.md 5.6 KB
📄 context7.json 2.7 KB
📄 LICENSE 1.1 KB
📄 README.md 2.9 KB
📄 ROADMAP.md 15.5 KB
📄 schemapin_mcp_demo.ipynb 32.2 KB
📄 SECURITY.md 4.3 KB
📄 SKILL.md 11.4 KB
📄 TECHNICAL_SPECIFICATION.md 16.3 KB
📄 zensical.toml 1.2 KB

SKILL.md

---
name: schemapin
title: SchemaPin
description: Cryptographic tool schema verification to prevent MCP Rug Pull attacks — ECDSA P-256 signing, SHA-256 hashing, TOFU key pinning, and .well-known discovery
version: 1.3.0
---

# SchemaPin Development Skills Guide

**Purpose**: This guide helps AI assistants quickly integrate SchemaPin into applications for cryptographic tool schema verification.

**For Full Documentation**: See the [README](https://github.com/ThirdKeyAI/SchemaPin/blob/main/README.md), [Technical Specification](https://github.com/ThirdKeyAI/SchemaPin/blob/main/TECHNICAL_SPECIFICATION.md), and language-specific READMEs in each subdirectory.

## What SchemaPin Does

SchemaPin prevents "MCP Rug Pull" attacks by enabling developers to cryptographically sign their tool schemas (ECDSA P-256 + SHA-256) and clients to verify schemas haven't been tampered with. It uses Trust-On-First-Use (TOFU) key pinning and RFC 8615 `.well-known` endpoints for public key discovery.

**Part of the ThirdKey trust stack**: SchemaPin (tool integrity) → AgentPin (agent identity) → Symbiont (runtime)

---

## Quick Start by Language

### Python

```bash
pip install schemapin
```

```python
from schemapin.crypto import KeyManager, SignatureManager
from schemapin.core import SchemaPinCore

# Generate keys
private_key, public_key = KeyManager.generate_keypair()

# Sign a schema
core = SchemaPinCore()
canonical = core.canonicalize_schema(schema_dict)
signature = SignatureManager.sign_schema(private_key, canonical)

# Verify
is_valid = SignatureManager.verify_signature(public_key, canonical, signature)
```

### JavaScript

```bash
npm install schemapin
```

```javascript
import { KeyManager, SignatureManager, SchemaPinCore } from 'schemapin';

// Generate keys
const { privateKey, publicKey } = KeyManager.generateKeypair();

// Sign a schema
const core = new SchemaPinCore();
const canonical = core.canonicalizeSchema(schema);
const signature = await SignatureManager.signSchema(privateKey, canonical);

// Verify
const isValid = await SignatureManager.verifySignature(publicKey, canonical, signature);
```

### Go

```bash
go get github.com/ThirdKeyAi/schemapin/go@v1.3.0
```

```go
import (
    "github.com/ThirdKeyAi/schemapin/go/pkg/core"
    "github.com/ThirdKeyAi/schemapin/go/pkg/crypto"
)

// Generate keys
km := crypto.NewKeyManager()
privKey, pubKey, _ := km.GenerateKeypair()

// Sign a schema
spc := core.NewSchemaPinCore()
canonical, _ := spc.CanonicalizeSchema(schema)
sig, _ := crypto.NewSignatureManager().SignSchema(privKey, canonical)

// Verify
valid, _ := crypto.NewSignatureManager().VerifySignature(pubKey, canonical, sig)
```

### Rust

```toml
[dependencies]
schemapin = "1.3"
```

```rust
use schemapin::crypto::{generate_key_pair, sign_data, verify_signature};
use schemapin::core::SchemaPinCore;

// Generate keys
let key_pair = generate_key_pair()?;

// Sign
let core = SchemaPinCore::new();
let canonical = core.canonicalize_schema(&schema)?;
let signature = sign_data(&key_pair.private_key_pem, &canonical)?;

// Verify
let is_valid = verify_signature(&key_pair.public_key_pem, &canonical, &signature)?;
```

---

## Core Concepts

### 1. Schema Canonicalization

Schemas are canonicalized (deterministic JSON serialization with sorted keys) before hashing. This ensures identical schemas always produce the same hash regardless of key ordering.

### 2. `.well-known` Discovery

Developers publish their public key at `https://example.com/.well-known/schemapin.json`:

```python
from schemapin.utils import create_well_known_response

response = create_well_known_response(
    public_key_pem=public_key_pem,
    developer_name="Acme Corp",
    schema_version="1.2",
    revocation_endpoint="https://example.com/.well-known/schemapin-revocations.json"
)
```

### 3. TOFU Key Pinning

On first verification, the developer's public key fingerprint is pinned. Subsequent verifications reject different keys for the same domain — detecting key substitution attacks.

### 4. Verification Workflows

**Online** (standard):
```python
workflow = SchemaVerificationWorkflow(pin_store)
result = workflow.verify_schema(schema, signature, "https://example.com")
```

**Offline** (v1.2.0 — no HTTP required):
```python
from schemapin.verification import verify_schema_offline, KeyPinStore

pin_store = KeyPinStore()
result = verify_schema_offline(
    schema, signature_b64, domain, tool_id,
    discovery_data, revocation_doc, pin_store
)
```

---

## v1.2.0 Features

### Standalone Revocation Documents

```python
from schemapin.revocation import (
    build_revocation_document, add_revoked_key,
    check_revocation, RevocationReason
)

doc = build_revocation_document("example.com")
add_revoked_key(doc, fingerprint, RevocationReason.KEY_COMPROMISE)
check_revocation(doc, some_fingerprint)  # raises if revoked
```

### Trust Bundles (Offline / Air-Gapped)

Pre-package discovery + revocation data for environments without internet:

```python
from schemapin.bundle import SchemaPinTrustBundle

bundle = SchemaPinTrustBundle.from_json(bundle_json_str)
discovery = bundle.find_discovery("example.com")
revocation = bundle.find_revocation("example.com")
```

### Pluggable Discovery Resolvers

```python
from schemapin.resolver import (
    WellKnownResolver,    # HTTP .well-known lookups
    LocalFileResolver,    # Local JSON files
    TrustBundleResolver,  # In-memory trust bundles
    ChainResolver,        # First-match fallthrough
)

# Chain: try bundle first, fall back to HTTP
resolver = ChainResolver([
    TrustBundleResolver.from_json(bundle_json),
    WellKnownResolver(timeout=10),
])
```

### Resolver-Based Verification

```python
from schemapin.verification import verify_schema_with_resolver

result = verify_schema_with_resolver(
    schema, signature_b64, domain, tool_id,
    resolver, pin_store
)
```

---

## v1.3.0 Features

### SkillSigner — File-Based Skill Folder Signing

Sign entire skill directories (e.g., a folder containing `SKILL.md`) with ECDSA P-256. Produces a `.schemapin.sig` manifest alongside the files, proving no file has been tampered with.

**Python:**
```python
from schemapin.skill import sign_skill, verify_skill_offline

# Sign a skill directory
sig = sign_skill("./my-skill/", private_key_pem, "example.com")
# Writes .schemapin.sig into ./my-skill/

# Verify offline
from schemapin.verification import KeyPinStore
result = verify_skill_offline("./my-skill/", discovery_data, sig, revocation_doc, KeyPinStore())
```

**JavaScript:**
```javascript
import { signSkill, verifySkillOffline } from 'schemapin/skill';

const sig = await signSkill('./my-skill/', privateKeyPem, 'example.com');
const result = verifySkillOffline('./my-skill/', discoveryData, sig, revDoc, pinStore);
```

**Go:**
```go
import "github.com/ThirdKeyAi/schemapin/go/pkg/skill"

sig, err := skill.SignSkill("./my-skill/", privateKeyPEM, "example.com", "", "")
result := skill.VerifySkillOffline("./my-skill/", disc, sig, rev, pinStore, "")
```

**Rust:**
```rust
use schemapin::skill::{sign_skill, verify_skill_offline};

let sig = sign_skill("./my-skill/", &private_key_pem, "example.com", None, None)?;
let result = verify_skill_offline("./my-skill/", &disc, Some(&sig), rev.as_ref(), Some(&pin_store), None);
```

### `.schemapin.sig` Format

```json
{
  "schemapin_version": "1.3",
  "skill_name": "my-skill",
  "skill_hash": "sha256:<root_hash>",
  "signature": "<base64_ecdsa_signature>",
  "signed_at": "2026-02-14T00:00:00Z",
  "domain": "example.com",
  "signer_kid": "sha256:<key_fingerprint>",
  "file_manifest": {
    "SKILL.md": "sha256:<file_hash>"
  }
}
```

### Tamper Detection

```python
from schemapin.skill import detect_tampered_files, canonicalize_skill

_, current_manifest = canonicalize_skill("./my-skill/")
tampered = detect_tampered_files(current_manifest, sig.file_manifest)
# tampered.modified, tampered.added, tampered.removed
```

---

## Server-Side Setup

### Publishing `.well-known` Endpoints

Python CLI tools are included:

```bash
# Generate a keypair
schemapin-keygen --output-dir ./keys

# Sign a schema
schemapin-sign --key ./keys/private.pem --schema schema.json

# Verify a signature
schemapin-verify --key ./keys/public.pem --schema schema.json --signature sig.b64
```

Go CLI equivalents are also available (`go install github.com/ThirdKeyAi/schemapin/go/cmd/...@v1.3.0`).

---

## Architecture

```
Developer                          Client (AI Platform)
─────────                          ────────────────────
1. Generate ECDSA P-256 keypair
2. Publish public key at           3. Discover public key from
   /.well-known/schemapin.json        /.well-known/schemapin.json
4. Sign tool schema                5. Verify signature
   (canonicalize → SHA-256            (canonicalize → SHA-256
    → ECDSA sign)                      → ECDSA verify)
                                   6. TOFU pin the key fingerprint
                                   7. Check revocation status
```

---

## Language API Reference

| Operation | Python | JavaScript | Go | Rust |
|-----------|--------|------------|----|----|
| Generate keys | `KeyManager.generate_keypair()` | `KeyManager.generateKeypair()` | `km.GenerateKeypair()` | `generate_key_pair()` |
| Sign schema | `SignatureManager.sign_schema()` | `SignatureManager.signSchema()` | `sm.SignSchema()` | `sign_data()` |
| Verify signature | `SignatureManager.verify_signature()` | `SignatureManager.verifySignature()` | `sm.VerifySignature()` | `verify_signature()` |
| Canonicalize | `SchemaPinCore().canonicalize_schema()` | `new SchemaPinCore().canonicalizeSchema()` | `spc.CanonicalizeSchema()` | `SchemaPinCore::new().canonicalize_schema()` |
| Discover key | `PublicKeyDiscovery.fetch_well_known()` | `PublicKeyDiscovery.fetchWellKnown()` | `FetchWellKnown()` | `WellKnownResolver` (fetch feature) |
| Offline verify | `verify_schema_offline()` | `verifySchemaOffline()` | `VerifySchemaOffline()` | `verify_schema_offline()` |
| Resolver verify | `verify_schema_with_resolver()` | `verifySchemaWithResolver()` | `VerifySchemaWithResolver()` | `verify_schema_with_resolver()` |
| Sign skill folder | `sign_skill()` | `signSkill()` | `skill.SignSkill()` | `sign_skill()` |
| Verify skill | `verify_skill_offline()` | `verifySkillOffline()` | `skill.VerifySkillOffline()` | `verify_skill_offline()` |
| Detect tampering | `detect_tampered_files()` | `detectTamperedFiles()` | `skill.DetectTamperedFiles()` | `detect_tampered_files()` |

---

## Testing

```bash
# Python
cd python && python -m pytest tests/ -v

# JavaScript
cd javascript && npm test

# Go
cd go && go test ./...

# Rust
cd rust && cargo test
```

---

## Pro Tips for AI Assistants

1. **Always canonicalize** before signing or verifying — raw JSON comparison will fail
2. **Use offline verification** when you have pre-fetched discovery data — avoids HTTP calls during schema validation
3. **Trust bundles** are ideal for CI/CD and air-gapped deployments
4. **ChainResolver** lets you layer resolvers: bundle → local files → HTTP as fallback
5. **TOFU pinning** means the first key seen for a domain is trusted — warn users on key changes
6. **All languages use the same crypto** — ECDSA P-256 + SHA-256, so cross-language verification works
7. **Revocation checking** should always be performed — both simple lists and standalone documents
8. **SkillSigner** signs entire directories — ideal for SKILL.md folders uploaded to registries like ClaWHub
9. **`.schemapin.sig`** is auto-excluded from hashing — you can re-sign a directory without removing the old signature first

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

schemapin

Directory Structure

SKILL.md

Report

Notice