proofnest 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

.planning/research/STACK.md

@@ -1,378 +0,0 @@
-# Technology Stack Research: PROOFNEST v1
-
-**Project:** PROOFNEST - AI Decisions You Can Prove
-**Researched:** 2026-02-03
-**Focus:** Stack GAPS for v1 milestones (brownfield analysis)
-
-## Executive Summary
-
-PROOFNEST already has solid cryptographic foundations (Dilithium3, Ed25519, hybrid signatures, OpenTimestamps). The gaps for v1 are primarily in **enterprise integration**, **production hardening**, and **AI-Human Hub platform capabilities**.
-
-## Current Stack (Already Implemented)
-
-| Component | Technology | Status | Notes |
-|-----------|------------|--------|-------|
-| Core API | Python 3.11 + FastAPI | Working | GPT-5.2 audited |
-| Blockchain | Go 1.21 | Testnet ready | 151K lines |
-| PQ Signatures | Dilithium3 (ML-DSA FIPS 204) | Working | cloudflare/circl in Go, dilithium_py in Python |
-| Classical Signatures | Ed25519 | Working | cryptography lib |
-| Hybrid Signatures | ML-DSA + Ed25519 | Working | GPT-5.2 recommendation |
-| Hash | SHAKE256, SHA3-256 | Working | Quantum-resistant |
-| Bitcoin Anchoring | OpenTimestamps | Working | Calendar servers integrated |
-| Consensus | HotStuff-2 BFT | Working | Python mock + Go real |
-| Identity | DID:PN | Working | Custom DID method |
-| Persistence | SQLite | Working | Full audit trail |
-| Authentication | API Key | Working | Basic, needs upgrade |
-
-**Confidence:** HIGH - verified via codebase analysis
-
----
-
-## GAPS: What's Missing for v1
-
-### M1: stellanium.io Operational
-
-#### Production Hardening
-
-| Gap | Recommended | Version | Why | Confidence |
-|-----|-------------|---------|-----|------------|
-| WSGI Server | Gunicorn + Uvicorn | 23.x / 0.30+ | Industry standard for FastAPI production | HIGH |
-| Rate Limiting | slowapi + Redis | 0.1.9+ / 7.2+ | Distributed rate limiting across instances | HIGH |
-| Observability | OpenTelemetry | 1.28+ | Distributed tracing, Prometheus metrics | HIGH |
-| Log Aggregation | Structured logging (structlog) | 25.x | JSON logs for observability stack | MEDIUM |
-| Health Checks | /health, /ready, /live | - | Kubernetes-ready probes | HIGH |
-
-**Source:** [FastAPI Production Deployment Guide](https://render.com/articles/fastapi-production-deployment-best-practices), [FastAPI Rate Limiting](https://www.techbuddies.io/2025/12/13/python-rate-limiting-for-apis-implementing-robust-throttling-in-fastapi/)
-
-#### Missing Infrastructure
-
-```yaml
-# Required additions to deployment
-services:
-  redis:
-    image: redis:7.2-alpine
-    # For rate limiting, session cache, pub/sub
-
-  prometheus:
-    image: prom/prometheus:latest
-    # Metrics collection
-
-  jaeger:
-    image: jaegertracing/all-in-one:latest
-    # Distributed tracing
-```
-
----
-
-### M2: First Enterprise Customer
-
-#### Enterprise Authentication (CRITICAL GAP)
-
-| Gap | Recommended | Why | Confidence |
-|-----|-------------|-----|------------|
-| OAuth 2.0 | authlib + python-jose | Industry standard, enterprise SSO | HIGH |
-| mTLS | Built-in TLS + cert validation | Zero-trust architecture | HIGH |
-| API Versioning | URL prefix (/v1/, /v2/) | Already using, expand | HIGH |
-| RBAC | Custom middleware | Role-based access control | MEDIUM |
-
-**Current state:** API key only. Enterprises need OAuth 2.0 client credentials, JWT validation.
-
-**Source:** [Enterprise API Security Architecture](https://www.informatica.com/resources/articles/enterprise-api-security-architecture.html)
-
-#### Enterprise SDK Requirements
-
-| Language | Priority | Recommended Approach |
-|----------|----------|---------------------|
-| TypeScript/Node | P0 | Official SDK with types |
-| Python | P0 | Already native (publish to PyPI) |
-| Go | P1 | Native client from existing code |
-| Java/Kotlin | P2 | For enterprise Android/backend |
-
-**SDK Features Needed:**
-- Automatic retry with exponential backoff
-- Webhook signature verification helpers
-- Proof creation/verification utilities
-- Async support (important for AI workloads)
-
-#### Webhook System (CRITICAL GAP)
-
-Current API is request-response only. Enterprises need event-driven integration.
-
-```python
-# MISSING: Webhook callback system
-class WebhookEvent(BaseModel):
-    event_type: str  # proof.created, proof.anchored, consensus.reached
-    proof_id: str
-    timestamp: int
-    payload: dict
-    signature: str  # HMAC-SHA256 for verification
-```
-
-| Event Type | When | Enterprise Use Case |
-|------------|------|---------------------|
-| proof.created | New proof submitted | Audit logging |
-| proof.validated | Consensus reached | Workflow trigger |
-| proof.anchored | Bitcoin confirmation | Compliance record |
-| proof.expired | TTL reached | Cleanup, alerts |
-
-**Source:** [Webhook Testing for API Callbacks](https://www.gravitee.io/blog/webhook-testing-for-api-callbacks)
-
-#### SLA Monitoring Requirements
-
-| Metric | Target | How to Measure |
-|--------|--------|----------------|
-| API Latency (p99) | <500ms | OpenTelemetry |
-| Proof Creation | <2s | Custom metric |
-| Consensus Time | <10s | Event timestamps |
-| Anchor Confirmation | <24h (Bitcoin) | Background job |
-| Uptime | 99.9% | Health checks |
-
----
-
-### M3: AI-Human Hub (Moltbook Competitor)
-
-#### Real-Time Capabilities (CRITICAL GAP)
-
-| Gap | Recommended | Why | Confidence |
-|-----|-------------|-----|------------|
-| WebSockets | FastAPI WebSocket + Redis Pub/Sub | Real-time AI decision feeds | HIGH |
-| Server-Sent Events | sse-starlette | Simpler alternative for one-way | MEDIUM |
-| Event Streaming | Redis Streams or Kafka | Scalable event backbone | MEDIUM |
-
-**Current:** REST API only. AI-Human Hub needs real-time.
-
-#### AI Decision Audit Trail (DIFFERENTIATOR)
-
-This is PROOFNEST's key value proposition for AI-Human Hub.
-
-```python
-# Required: Cryptographic Audit Trail API
-class AIDecisionProof(BaseModel):
-    """EU AI Act Article 12 compliant audit record"""
-    model_id: str           # e.g., "gpt-5.2", "claude-4"
-    model_version: str
-    input_hash: str         # SHAKE256 of input
-    output_hash: str        # SHAKE256 of output
-    reasoning_hash: str     # Chain of Thought hash
-    timestamp: int
-    latency_ms: int
-    confidence: float       # Model's confidence if available
-    human_verified: bool    # Was this reviewed?
-    verifier_did: Optional[str]
-```
-
-**Source:** [Audit Trails for AI: How to Prove an Agent's Work](https://chatfin.ai/blog/audit-trails-for-ai-how-to-prove-an-agents-work-to-the-auditors/), [Using Blockchain Ledgers to Record AI Decisions](https://www.mdpi.com/2624-831X/6/3/37)
-
-**Regulatory Context:** By August 2, 2026, EU AI Act requires transparency and audit trails for high-risk AI systems. PROOFNEST can be THE compliance solution.
-
-**Source:** [AI Regulatory Compliance 2026](https://sombrainc.com/blog/ai-regulations-2026-eu-ai-act)
-
-#### Multi-Tenant Architecture
-
-| Component | Current | Needed |
-|-----------|---------|--------|
-| Database | Single SQLite | PostgreSQL with tenant isolation |
-| API Keys | Global | Per-tenant with scopes |
-| Identity | DID:PN only | Link to social (Twitter, GitHub) |
-| Rate Limits | None | Per-tenant tiers |
-| Storage | Local | S3-compatible with tenant buckets |
-
-#### Trust Verification API (Moltbook Differentiator)
-
-Moltbook leaked 1.5M API keys because of weak trust model. PROOFNEST's differentiator:
-
-```python
-# Trust Verification Endpoints
-GET  /v1/trust/{did}/score           # Trust score based on proof history
-GET  /v1/trust/{did}/attestations    # Who attests to this identity
-POST /v1/trust/verify-ai-output      # Verify AI output was proven
-GET  /v1/trust/chain/{proof_id}      # Full proof chain to Bitcoin
-```
-
----
-
-## Cryptography Stack: 2026 Standards
-
-### FIPS Compliance Status
-
-| Standard | Algorithm | PROOFNEST Status | Notes |
-|----------|-----------|------------------|-------|
-| FIPS 204 | ML-DSA (Dilithium) | Implemented | Primary signatures |
-| FIPS 203 | ML-KEM | Not needed | Key exchange (TLS handles) |
-| FIPS 205 | SLH-DSA (SPHINCS+) | Not implemented | Alternative, larger signatures |
-
-**Recommendation:** Current Dilithium3 implementation is FIPS 204 compliant. No changes needed.
-
-**Source:** [NIST FIPS 204](https://csrc.nist.gov/pubs/fips/204/final), [NIST PQC Standards](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards)
-
-### Go Cryptography Status (Go 1.24+)
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| crypto/mlkem | Available | Hybrid X25519+ML-KEM-768 in crypto/tls |
-| ML-DSA | NOT in stdlib | Use cloudflare/circl (current approach is correct) |
-| Hybrid TLS | Default | Go 1.24 auto-negotiates |
-
-**Source:** [Post-Quantum Cryptography for Go](https://words.filippo.io/mlkem768/), [2025 Go Cryptography State](https://words.filippo.io/2025-state/)
-
-**Recommendation:** Keep using cloudflare/circl for Dilithium. Go stdlib covers TLS.
-
-### Bitcoin Anchoring: OpenTimestamps
-
-Current implementation is correct. Enhancement opportunities:
-
-| Feature | Current | Enhancement |
-|---------|---------|-------------|
-| Calendar servers | 3 servers | Add redundancy with own calendar |
-| Verification | External | Add local Bitcoin Core verification |
-| Batching | Per-proof | Merkle tree batching (10K proofs/tx) |
-
-**Source:** [OpenTimestamps](https://opentimestamps.org/), [OpenTimestamps Guide](https://dgi.io/ots/)
-
----
-
-## Recommended New Dependencies
-
-### Python (Core API)
-
-```toml
-# pyproject.toml additions
-[project.dependencies]
-# Production
-gunicorn = ">=23.0"
-slowapi = ">=0.1.9"
-redis = ">=5.0"
-structlog = ">=25.1"
-
-# Observability
-opentelemetry-api = ">=1.28"
-opentelemetry-sdk = ">=1.28"
-opentelemetry-instrumentation-fastapi = ">=0.49"
-prometheus-fastapi-instrumentator = ">=7.0"
-
-# Enterprise Auth
-authlib = ">=1.4"
-python-jose = ">=3.3"
-
-# Real-time
-websockets = ">=13.0"
-redis = ">=5.0"  # For pub/sub
-```
-
-### Go (Blockchain)
-
-```go
-// go.mod additions - mostly already present
-require (
-    github.com/cloudflare/circl v1.5.0  // Already using
-    github.com/prometheus/client_golang v1.20.0
-    go.opentelemetry.io/otel v1.32.0
-)
-```
-
-### TypeScript (SDK - New)
-
-```json
-{
-  "name": "@proofnest/sdk",
-  "dependencies": {
-    "axios": "^1.7.0",
-    "ws": "^8.18.0",
-    "@noble/hashes": "^1.5.0"
-  }
-}
-```
-
----
-
-## Architecture Implications
-
-### Current Architecture
-```
-Client -> FastAPI -> SQLite
-                  -> Bitcoin (OpenTimestamps)
-                  -> Go Chain (internal)
-```
-
-### v1 Architecture
-```
-Client -> API Gateway (rate limiting, auth)
-       -> FastAPI (Gunicorn+Uvicorn)
-          -> PostgreSQL (multi-tenant)
-          -> Redis (cache, pub/sub, rate limits)
-          -> Go Chain (consensus, proofs)
-          -> Bitcoin (OpenTimestamps)
-          -> Webhooks (event callbacks)
-       -> WebSocket Server (real-time)
-       -> Prometheus/Jaeger (observability)
-```
-
----
-
-## Priority Matrix
-
-| Gap | Milestone | Priority | Effort | Risk if Skipped |
-|-----|-----------|----------|--------|-----------------|
-| Rate Limiting | M1 | P0 | Low | DoS vulnerability |
-| Observability | M1 | P0 | Medium | Blind to issues |
-| OAuth 2.0 | M2 | P0 | Medium | No enterprise sales |
-| Webhooks | M2 | P0 | Medium | Poor integration |
-| TypeScript SDK | M2 | P1 | Medium | Limited adoption |
-| WebSockets | M3 | P0 | Medium | No real-time |
-| AI Audit Trail API | M3 | P0 | Low | Miss EU AI Act opportunity |
-| PostgreSQL Migration | M3 | P1 | High | Scale ceiling |
-
----
-
-## Alternatives Considered
-
-| Category | Recommended | Alternative | Why Not Alternative |
-|----------|-------------|-------------|---------------------|
-| Rate Limiting | slowapi + Redis | fastapi-limiter | slowapi more mature |
-| Observability | OpenTelemetry | Datadog SDK | Vendor lock-in |
-| Real-time | WebSocket + Redis | Kafka | Overkill for v1 scale |
-| Auth | authlib | Auth0 SDK | Keep control, reduce cost |
-| Database | PostgreSQL | CockroachDB | PostgreSQL sufficient for v1 |
-
----
-
-## Confidence Assessment
-
-| Area | Level | Reason |
-|------|-------|--------|
-| Cryptography | HIGH | FIPS 204 verified, codebase reviewed |
-| Production Hardening | HIGH | Well-documented patterns |
-| Enterprise Integration | MEDIUM | Depends on customer requirements |
-| AI-Human Hub | MEDIUM | Emerging patterns, less proven |
-| Regulatory | HIGH | EU AI Act requirements clear |
-
----
-
-## Sources
-
-### Cryptography & Standards
-- [NIST FIPS 204 (ML-DSA)](https://csrc.nist.gov/pubs/fips/204/final) - HIGH confidence
-- [NIST PQC Announcement](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards) - HIGH confidence
-- [Go Post-Quantum Roadmap](https://github.com/golang/go/issues/64537) - HIGH confidence
-- [Cloudflare CIRCL](https://blog.cloudflare.com/introducing-circl/) - HIGH confidence
-
-### Bitcoin Anchoring
-- [OpenTimestamps](https://opentimestamps.org/) - HIGH confidence
-- [OpenTimestamps Tutorial](https://dgi.io/ots-tutorial/) - HIGH confidence
-
-### Enterprise Integration
-- [Enterprise API Security](https://www.informatica.com/resources/articles/enterprise-api-security-architecture.html) - MEDIUM confidence
-- [Webhook Best Practices](https://www.gravitee.io/blog/webhook-testing-for-api-callbacks) - MEDIUM confidence
-
-### AI Compliance
-- [EU AI Act Compliance 2026](https://sombrainc.com/blog/ai-regulations-2026-eu-ai-act) - HIGH confidence
-- [AI Audit Trails](https://chatfin.ai/blog/audit-trails-for-ai-how-to-prove-an-agents-work-to-the-auditors/) - MEDIUM confidence
-- [Blockchain for AI Decisions](https://www.mdpi.com/2624-831X/6/3/37) - MEDIUM confidence
-
-### Production Deployment
-- [FastAPI Production Guide](https://render.com/articles/fastapi-production-deployment-best-practices) - HIGH confidence
-- [FastAPI Rate Limiting](https://www.techbuddies.io/2025/12/13/python-rate-limiting-for-apis-implementing-robust-throttling-in-fastapi/) - MEDIUM confidence
-
----
-
-*Research complete. This informs roadmap creation for v1 milestones.*