Skip to content

implementation.md

Latest commit

 

History

History
355 lines (279 loc) · 12.4 KB

implementation.md

File metadata and controls

355 lines (279 loc) · 12.4 KB
Raw

Keysmith Development Plan

Project Overview

Keysmith is an open-source license & entitlements server with signed offline checks, simple updates, and thin Stripe/Polar adapters.

Tech Stack: Encore.ts (TypeScript), PostgreSQL, Pub/Sub, Cron, Secrets
Frontend: React + Vite + Tailwind CSS
Target: OSS Hackathon Submission

📊 Current Progress Status

Phase Status Completion Key Features
Phase 1: Core Foundation ✅ COMPLETED 100% Ed25519 signing, offline verification, device management
Phase 2: Webhook Integration ✅ COMPLETED 100% Stripe webhooks, automated license lifecycle
Phase 3: Admin Interface ✅ COMPLETED 100% Full admin UI, CRUD operations, status management
Phase 4: Updates & Releases ✅ COMPLETED 100% Software update distribution system
Phase 5: Customer Portal 🟡 IN PROGRESS 25% Magic link auth, license viewing
Phase 6: Polish & Production 📋 PLANNED 0% Production hardening, documentation

🎯 Overall Progress: 4.25/6 Phases Complete (~70%)
🚀 Next Up: Finish Customer Portal UI

✅ What's Working Right Now:

  • Complete Licensing Engine - Create, validate, revoke licenses
  • Offline Verification - Ed25519 signatures work without internet
  • Stripe Integration - Automated license lifecycle via webhooks
  • Professional Admin UI - Manage products, licenses, templates, events
  • Device Management - Activation limits and device tracking
  • Software Updates - Publish, list, and block releases via admin UI
  • Customer Portal Backend - Magic link auth and license viewing APIs are done
  • Comprehensive Demo Data - Full working examples out of the box

Development Phases

Phase 1: Core Foundation (Priority 1) 🎯

Goal: Get the essential licensing engine working with offline verification

Backend Services

  • Database Schema & Migrations

    • Products, customers, licenses, activations tables
    • Entitlement templates, events, versions tables
    • Proper indexes and constraints

  • Licensing Service (backend/licensing/)

    • Ed25519 key generation and management
    • License minting with JWT signing
    • License validation (online check)
    • License revocation
    • Public key endpoint for offline verification

  • Entitlements Service (backend/entitlements/)

    • Template CRUD operations
    • Signed entitlements payload generation
    • Template-to-license mapping

  • Activations Service (backend/activations/)

    • Device activation with seat limits
    • Device deactivation
    • Activation quota checking

Infrastructure Setup

  • Secrets Configuration

    • Ed25519PrivateKey
    • MagicLinkSecret (for future use)
    • RESEND_API_KEY (for emails)

  • Basic Pub/Sub Topics

    • license.events topic setup
    • Basic event publishing

API Endpoints (Core)

  • POST /v1/licenses - Create license
  • POST /v1/licenses/{id}/revoke - Revoke license
  • GET /v1/validate - Online validation
  • GET /v1/public_key - Public key for offline verification
  • GET /v1/entitlements/{license_key} - Signed entitlements
  • POST /v1/activate - Device activation
  • POST /v1/deactivate - Device deactivation

Testing & Documentation

  • Unit tests for signing/verification
  • Unit tests for activation quotas
  • Basic integration tests
  • Client verification examples (TypeScript, curl)

Deliverable: Working licensing engine with offline verification capability

Phase 2: Webhook Integration (Priority 2) 🔗

Goal: Handle Stripe webhooks and automate license lifecycle

Webhook Services

  • Webhooks Service (backend/webhooks/)

    • Stripe webhook endpoint with signature verification
    • Event normalization to internal format
    • Idempotency handling with events table
    • Pub/Sub event publishing

  • Billing Events Processor

    • Subscribe to billing.events topic
    • License creation from LICENSE_ISSUE events
    • License renewal from LICENSE_RENEW events
    • License suspension/revocation

Secrets Addition

  • StripeWebhookSecret configuration

API Endpoints

  • POST /webhooks/stripe - Stripe webhook handler

Testing

  • Webhook signature verification tests
  • Event normalization tests
  • Idempotency tests with sample Stripe payloads

Deliverable: Automated license management via Stripe webhooks

Phase 3: Admin Interface (Priority 3) ✅ COMPLETED

Goal: Web UI for license management and monitoring

Admin Backend

  • Admin Service (backend/admin/)
    • License listing and filtering
    • License creation/modification endpoints
    • Product CRUD endpoints (create, update, list)
    • Dashboard statistics (active licenses, expiring soon)
    • Entitlement template management (full CRUD)
    • Webhook events monitoring

Frontend Application

  • Admin UI (frontend/)
    • Dashboard with KPIs and charts
    • License management (list, create, edit with status control)
    • Product management (list, create, edit with metadata)
    • Entitlement template editor (JSON with validation)
    • Webhook events monitoring
    • Basic authentication (simple admin key for MVP)
    • Frontend hosting configured via encore.app.ts

API Endpoints (Admin)

  • GET /v1/admin/dashboard - Dashboard statistics
  • GET /v1/admin/licenses - List licenses with filters
  • POST /v1/admin/licenses - Create license manually
  • PUT /v1/admin/licenses/:id - Update license (including status)
  • GET /v1/admin/products - List all products
  • POST /v1/admin/products - Create new product
  • PUT /v1/admin/products/:id - Update existing product
  • GET /v1/admin/entitlements/templates - List templates
  • POST /v1/admin/entitlements/templates - Create template
  • PUT /v1/admin/entitlements/templates/:id - Update template
  • GET /v1/admin/events - Recent webhook events

UI Components

  • License table with status indicators and filtering
  • Product table with CRUD operations
  • JSON editor for entitlement templates with validation
  • Dashboard cards with license statistics
  • Event log viewer with pagination
  • Professional forms with validation (Zod + react-hook-form)
  • Status management dropdown (active/suspended/revoked/expired)

Deliverable: ✅ COMPLETED - Full admin interface for license, product, and template management

Phase 4: Updates & Releases (Priority 4) 📦

Goal: Signed software update distribution

Updates Service

  • Updates Service (backend/updates/)
    • Release publishing with signature generation (signature provided by user)
    • Channel management (stable/beta)
    • Manifest generation and serving
    • Version blocking capability

Database Extensions

  • Versions table population and management
  • Channel-based queries with proper indexing

API Endpoints

  • POST /v1/admin/updates/publish - Publish new release (admin)
  • GET /v1/updates/:product_slug/:channel - Update manifest
  • GET /v1/admin/updates - List releases
  • POST /v1/admin/updates/:id/block - Block/unblock release

Admin UI Extensions

  • Release management interface
  • Channel switching and version history (partially done with channel field)
  • Release notes editor (via metadata)

Deliverable: Complete software update distribution system

Phase 5: Customer Portal (Priority 5) 👥

Goal: Self-service customer interface

Portal Backend

  • Portal Service (backend/portal/)
    • Magic link generation and validation
    • Customer session management
    • License viewing for authenticated customers
    • Device reset functionality

Portal Frontend

  • Customer Portal (frontend/portal/)
    • Magic link login flow (UI components created)
    • License overview with entitlements
    • Device management and reset
    • Download links for updates

Secrets Addition

  • MagicLinkSecret
  • ResendApiKey (secret defined, email sending not implemented)

API Endpoints

  • POST /v1/portal/request-link - Request magic link
  • POST /v1/portal/session - Validate magic link and create session
  • GET /v1/portal/my-licenses - Customer's licenses
  • POST /v1/portal/reset-device - Self-service device reset

Deliverable: Customer self-service portal (In Progress)

Phase 6: Polish & Production Ready (Priority 6) ✨

Goal: Production deployment and comprehensive documentation

Infrastructure Enhancements

  • Cron Jobs

    • License expirer (hourly)
    • Expiry reminder emails (daily)

  • Additional Webhooks

    • Polar webhook support
    • Webhook retry mechanism with exponential backoff

Security & Performance

  • Rate limiting implementation
  • Input validation with Zod
  • Security headers and CORS configuration
  • Database query optimization

Documentation & Examples

  • Comprehensive README with setup instructions
  • Client verification examples (TypeScript, Python, Go)
  • API documentation (auto-generated by Encore)
  • Deployment guide for AWS/GCP
  • Architecture diagram

Testing & Quality

  • End-to-end integration tests
  • Performance testing for validation endpoints
  • Security audit of webhook verification
  • Error handling and logging improvements

Demo Preparation

  • Seed script with realistic demo data
  • Demo scenarios and test flows
  • Video demo recording
  • Live deployment for judges to test

Deliverable: Production-ready system with comprehensive documentation

Success Metrics

Technical Metrics

  • License validation response time < 100ms
  • Webhook processing time < 500ms
  • 99.9% uptime for core licensing APIs
  • Zero license key collisions
  • Successful offline verification in multiple languages

Feature Completeness

  • Complete Stripe integration with all event types
  • Working offline verification examples
  • Functional admin interface
  • Customer self-service portal
  • Automated license lifecycle management

Documentation Quality

  • One-command local setup
  • Clear API documentation with examples
  • Multiple client language examples
  • Deployment guides for major cloud providers

Development Notes

Dependencies & Libraries

  • Ed25519: @noble/ed25519 for modern crypto
  • JWT: jose library for EdDSA support
  • Validation: zod for runtime type checking
  • UI: shadcn/ui components with Tailwind
  • Email: Resend for reliable delivery

Database Considerations

  • Use UUIDs for all primary keys
  • Add metadata JSONB fields for extensibility
  • Implement soft deletes for audit trails
  • Consider partitioning for the events table

Security Best Practices

  • Never log license keys or secrets
  • Implement request signing for admin APIs
  • Use secure session handling for portal
  • Validate all webhook signatures
  • Rate limit public endpoints

Performance Optimizations

  • Cache public key endpoint response
  • Use database indexes effectively
  • Implement connection pooling
  • Consider read replicas for high-traffic validation

Risk Mitigation

Technical Risks

  • Ed25519 browser compatibility: Test in all target environments early
  • Webhook delivery failures: Implement retry mechanism with dead letter queue
  • Database migrations: Test migration rollback procedures
  • Key rotation: Plan for Ed25519 key rotation without breaking existing licenses

Scope Risks

  • Feature creep: Stick to defined phases and MVP features
  • Over-engineering: Focus on working solution over perfect architecture
  • Time management: Prioritize core licensing over UI polish for hackathon

Demo Risks

  • Network dependencies: Have offline demos ready
  • Data consistency: Ensure demo data is realistic and compelling
  • Platform issues: Test on multiple browsers and devices

Next Steps

  1. Review and approve this development plan
  2. Set up Encore.ts project structure
  3. Begin Phase 1 with database schema design
  4. Implement core licensing service
  5. Create basic offline verification examples

Estimated Timeline: 5-7 days for core functionality (Phases 1-3), additional time for polish and advanced features.