Signet Protocol

Secure, verifiable, auditable AI-to-AI exchanges ("Trust Fabric").
Signed receipts & hash‑chained audit trails for every normalized transformation and optional forward delivery.

🆕 NEW: AI Act Compliance Kit - Turn cryptographic receipts into ready-made conformity dossiers (EU AI Act / NIST AI RMF / ISO 42001) with one-click technical documentation, post-market monitoring, and regulator export bundles.

⭐ If this helps you build safer AI systems, please Star the repo — it signals demand and unlocks more OSS investment.

---

Repository Layout (Key Paths)

signet-protocol/
├─ server/
│  ├─ rtl/                # Transparency log (Merkle tree, STH signer)
│  ├─ forward/pch.py      # Proof-Carrying HTTP (signed outbound headers)
│  ├─ identity/           # DID document & pluggable signer (software / hw)
│  └─ ...                 # FastAPI app & pipeline modules
├─ sdk/
│  ├─ node/pch-express/   # Express middleware verifying PCH signatures
│  ├─ python/signet_pch_fastapi/ # FastAPI middleware for PCH verification
│  └─ wasm/verify/        # WASM receipt / Merkle proof verifier
├─ specs/                 # Draft feature specifications
│  ├─ RTL-1-TRANSPARENCY-LOG.md
│  ├─ PCH-1-PROOF-CARRYING-HTTP.md
│  └─ DID-1-KEY-BINDING.md
├─ tools/
│  ├─ signet_cli.py       # General CLI
│  └─ signet_rtl_cli.py   # Transparency log proof fetch & verify
└─ vscode-extension/      # Signet Lens (receipt visualization)

Specs capture evolving cryptographic / interoperability contracts; implementations may have placeholder algorithms (e.g., current PCH HMAC placeholder → upcoming Ed25519/JWS upgrade).

---

AI Act Compliance Kit

Transform cryptographic receipts into ready-made conformity dossiers for EU AI Act, NIST AI RMF, and ISO 42001 compliance.

One-Click Technical Documentation

# Generate complete AI Act Annex IV dossier
curl -H "X-SIGNET-API-Key: demo_key" \
  http://localhost:8088/v1/compliance/annex-iv/my-system?format=json

# Export for regulators with cryptographic integrity
curl -X POST -H "X-SIGNET-API-Key: demo_key" \
  http://localhost:8088/v1/compliance/retention/export \
  -d '{"profile_name": "general_audit", "date_range": {"start": "2024-01-01T00:00:00Z", "end": "2024-12-31T23:59:59Z"}}'

Compliance Modules

Module	Purpose	AI Act Coverage
Annex IV Generator	Technical documentation dossier	Articles 11, 47-48
Retention Manager	10-year data retention & regulator exports	Article 12
Post-Market Monitoring	Performance drift detection & PMM reports	Article 61
Risk Manager	NIST AI RMF compliance & risk assessment	Article 9
CE Marking Generator	EU conformity assessment & declaration	Articles 47-48
GPAI Transparency	General Purpose AI disclosures	GPAI obligations

Key Benefits

• Procurement Unblocker: Answer RFP questions with signed evidence, not promises
• Sales Acceleration: Pre-built dossiers reduce legal review cycles by 20-40%
• Verifiable Evidence: Cryptographically signed proofs that auditors can independently verify
• Cross-Standard Coverage: One implementation covers AI Act, NIST AI RMF, and ISO 42001
• Automated Monitoring: Real-time drift detection and compliance status tracking

Quick Demo

# Get unified compliance dashboard
import requests
headers = {'X-SIGNET-API-Key': 'demo_key'}
dashboard = requests.get('http://localhost:8088/v1/compliance/dashboard', headers=headers).json()
print(f"Compliance status: {dashboard['retention_status']['compliant']}")

# Generate PMM report
pmm_report = requests.post('http://localhost:8088/v1/compliance/pmm-report', 
  headers=headers, 
  json={
    "system_id": "my-ai-system",
    "start_date": "2024-01-01T00:00:00Z", 
    "end_date": "2024-12-31T23:59:59Z"
  }).json()

📖 Full Documentation: See docs/COMPLIANCE_FEATURES.md for complete API reference and regulatory mapping.

Safeguards & Hardening

The Compliance Kit provides cryptographically verifiable evidence & controls — not legal advice and not, by itself, a conformity assessment or CE mark.

• Default Redaction Policy: Non‑admin tokens automatically receive redacted export bundles (HardeningDefault = ON). Sensitive fields are zeroed / masked prior to serialization.
• Tamper‑Evidence: Every export includes a manifest (SHA‑256 hashes) for each file plus the ordered list of receipt CIDs; recomputation must match or verification fails.
• Time‑Bound Proofs: Export response headers include Date and X-Signet-Valid-For: <duration> (e.g. 7d). Re-verifiers MUST reject proofs presented outside the validity window unless re-fetched.
• Scoped Access Control: All /v1/compliance/* read endpoints require the compliance.read scope. Mutation / configuration endpoints are restricted to admin tokens (admin=true, scope: compliance.write).
• Lightweight PII Heuristics: Payload scanning (regex + entropy + format checks) flags potential residual PII that escaped redaction; flagged fields are annotated in the dossier and surfaced via the dashboard.
• Performance Target: Dossier generation is parallelized (I/O + hash verification) with a target p95 < 8s for a 30‑day window (baseline: ~N receipts) to keep CI / audit pipelines fast.
• Defense in Depth: Signed receipts + Merkle linkage + hash manifest prevent silent mutation; scope gating + default redaction constrain blast radius of key leakage.

Planned hardening extensions: hardware-backed signer attestation, structured differential privacy summaries for monitored metrics, configurable PII classifier model upgrade path.

---

Pull Quotes

“The AI Act Compliance Kit is the killer feature—signed evidence, not promises.”
— Independent technical review

“Cryptography‑first design: hash‑chained, signed receipts with deterministic canonicalization.”
— Independent technical review

“Proof‑Carrying HTTP lets trust propagate across service boundaries.”
— Independent technical review

“Transparency Log (RTL) provides a tamper‑proof record of exchanges, CT‑style.”
— Independent technical review

“VS Code Signet Lens turns audits into a click: visualize and verify chain integrity.”
— Independent technical review

---

Why Signet?

Problem Without Signet	With Signet
Opaque AI tool calls / prompt chains	Cryptographically signed, replayable trail
Hard to prove no tampering	Hash‑linked receipts (detect single‑byte mutation)
Ad‑hoc logging (no integrity)	Canonical JSON + deterministic hashing (RFC 8785)
Unbounded egress risk (SSRF, data exfil)	HEL policy + allowlist + IP pinning
"Trust me" billing	Unit & token metering + exportable billing evidence
Post‑incident forensic gaps	Export bundle: portable ground truth chain

---

Top Use Cases

Use Case	Benefit
Multi-agent orchestration	Prove which agent produced which transformed fields
Regulated data workflows (fintech, healthcare)	Immutable audit for compliance & dispute resolution
Usage-based AI billing platforms	Transparent, verifiable unit attribution
Supply chain / output provenance	Attest each normalization / enrichment hop
Security boundary enforcement	Prevent unauthorized outbound calls & data leakage
Failure & drift analysis	Compare historical, signed normalized outputs over time

---

Extended Examples

A. End-to-End (Python)

import requests, json
API = 'http://localhost:8088'
H = {
  'X-SIGNET-API-Key': 'demo_key',
  'X-SIGNET-Idempotency-Key': 'demo-001',
  'Content-Type': 'application/json'
}
payload = {
  'payload_type': 'openai.tooluse.invoice.v1',
  'target_type': 'invoice.iso20022.v1',
  'payload': { 'tool_calls': [] }
}
# Exchange
x = requests.post(f'{API}/v1/exchange', headers=H, json=payload).json()
print('Normalized amount:', x['normalized'].get('amount_minor'))
# Export chain
bundle = requests.post(f'{API}/v1/export/bundle', headers=H, json={'trace_id': x['trace_id']}).json()
print('Receipts in chain:', len(bundle['receipts']))

B. Tamper Detection (Illustrative)

If an attacker flips a digit inside a recorded normalized field:

from copy import deepcopy
from signet_verify import verify_receipt
r = bundle['receipts'][0]
print(verify_receipt(r))  # (True, None)
mut = deepcopy(r)
mut['normalized']['amount_minor'] = 999999  # tamper
print(verify_receipt(mut))  # (False, 'hash mismatch')

A single‑field mutation alters the canonical serialization hash; verification fails immediately.

C. LangChain Integration

from signet_callback import enable_signet_verification
signet = enable_signet_verification(API, 'demo_key')
result = chain.run("make invoice", callbacks=[signet])

---

Trust Fabric Concepts (Plain Language)

Term	Plain Meaning
VEx (Verified Exchange)	A single normalized + signed step in a multi-hop chain
Receipt	JSON envelope: content CID, previous hash, signature, timestamp
Bundle	Exported ordered list of receipts (plus root metadata)
Semantic Invariant	Rule that critical fields must not structurally change
HEL Policy	Outbound network policy (host / method / size / timeout)

---

Quick Start (3 Paths)

1. Run Locally (Python)

git clone https://github.com/Maverick0351a/signet-protocol
cd signet-protocol
pip install -r requirements.txt
uvicorn server.main:app --port 8088

Health check:

curl http://localhost:8088/healthz

2. Docker

docker build -t signet .
docker run -p 8088:8088 -e SP_API_KEYS='{"demo_key":{"tenant":"acme","fallback_enabled":true}}' signet

3. Hosted Demo (Fly.io)

Base URL: https://signet-protocol.fly.dev

---

Make an Exchange

curl -X POST http://localhost:8088/v1/exchange \
  -H "X-SIGNET-API-Key: demo_key" \
  -H "X-SIGNET-Idempotency-Key: unique-123" \
  -H "Content-Type: application/json" \
  -d '{
    "payload_type": "openai.tooluse.invoice.v1",
    "target_type": "invoice.iso20022.v1",
    "payload": {"tool_calls": []}
  }'

Response (trimmed):

{
  "trace_id": "demo-abc-123",
  "normalized": {"invoice_id": "INV-001"},
  "receipt": {"hop":1,"cid":"sha256:...","receipt_hash":"sha256:..."}
}

---

Verify a Receipt (SDKs)

JavaScript:

npm install signet-verify-js

import { verifyReceipt } from 'signet-verify-js';
const { valid } = verifyReceipt(receipt);

Python:

pip install signet-verify

from signet_verify import verify_receipt
valid, reason = verify_receipt(receipt)

LangChain (one‑liner callback):

from signet_callback import enable_signet_verification
signet = enable_signet_verification("http://localhost:8088", "demo_key")
chain.run("example", callbacks=[signet])

---

VS Code Extension (Signet Lens)

Visualize & diff receipt chains directly in the editor.

code --install-extension odinsecureai.signet-lens

Commands: Verify Receipt Chain • Visualize Chain • Copy Bundle CID • Diff CID

---

Generated API Clients

Frozen spec snapshots live in docs/api/ (e.g. openapi-v1.0.0.yaml).

Publish flows (automated):

• TypeScript npm: tag client-ts-vX.Y.Z
• Python PyPI: tag client-py-vX.Y.Z

Generate locally:

./scripts/generate_clients.sh 1.0.0

Details: clients/README.md.

---

Key Endpoints

Endpoint	Purpose
GET /healthz	Liveness check
GET /metrics	Prometheus metrics
GET /.well-known/jwks.json	Public keys
POST /v1/exchange	Submit + normalize + sign
POST /v1/export/bundle	Export signed chain
POST /v1/admin/reload-reserved	Reload billing config

---

Security & Integrity Highlights

• RFC 8785 JSON canonicalization (stable hashing)
• Ed25519 signatures with published JWKS
• Idempotency keys prevent accidental replays
• SSRF & DNS rebinding defenses (IP pinning, allowlists)
• Size & time limits for outbound fetches
• Semantic invariant validation (rejects mutated critical fields)

---

Observability

Prometheus metrics & OpenTelemetry spans are enabled by default. Enable tracing export:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=signet-protocol

Sample metrics (names may evolve):

signet_exchanges_total
signet_exchange_total_latency_seconds_bucket
signet_repair_attempts_total
signet_vex_units_total
signet_fu_tokens_total

Starter Grafana dashboards: monitoring/grafana/.

---

Billing (Optional)

• Verified Exchange units (VEx) + Fallback Unit tokens (FU)
• Reserved capacity per tenant
• Stripe integration for product & link setup (/v1/billing/* endpoints)

To enable billing locally provide API keys and run setup script (see STRIPE_MCP_INTEGRATION_GUIDE.md).

---

Export & Offline Verification

Export a chain:

curl -X POST http://localhost:8088/v1/export/bundle \
  -H "X-SIGNET-API-Key: demo_key" -d '{"trace_id": "demo-abc-123"}' -o bundle.json

Verify offline using JS or Python SDK: load each receipt, canonicalize, recompute hash, match chain.

---

Documentation Map

Topic	Location
Receipt Spec	docs/SR-1-SIGNET-RECEIPT-SPEC.md
Verified Exchange Spec	docs/SVX-1-VERIFIED-EXCHANGE-SPEC.md
Trust Fabric Overview	docs/TRUST-FABRIC-STANDARD.md
Deployment	DEPLOYMENT_GUIDE.md
Advanced Features	ADVANCED_FEATURES.md
Branding	docs/BRANDING.md
Developer Internals	DEVELOPERS.md

---

Production Readiness Checklist

Item	Status
Canonical JSON receipt spec frozen (v1.0.0)	✅
End-to-end tests (52 pass)	✅
Metrics & tracing instrumentation	✅
Export bundle & offline verify	✅
Billing & reserved capacity	✅
LangChain & SDK verification libs	✅
Security controls (SSRF / IP pinning / invariants)	✅
Fallback repair + semantic guardrails	✅
Frozen OpenAPI for client generation	✅

---

Contributing

Issues & PRs welcome. See DEVELOPERS.md for workflows, lint, release tags. Quick dev loop:

pip install -r requirements.txt
pytest tests/ -q
uvicorn server.main:app --reload --port 8088

---

License

Apache 2.0 (see LICENSE).

---

Building the Trust Fabric for AI systems.