LicenseEye — Repo Overview

This repository implements an enterprise-grade license management platform with a Cloudflare Workers backend, a React admin UI, and a TypeScript client SDK.

This top-level README documents the purpose and contents of each folder, common development commands, deployment, and links to security and publishing guides.

---

🚀 Quick Start

• See QUICKSTART.md for a step-by-step setup guide.
• See SECURITY.md for security best practices.
• See PUBLISHING.md for npm publishing and production deployment.

---

---

Repository layout

• admin/ — React-based Admin UI (Vite + React + Ant Design)
  • Purpose: product/feature schema editing, policy management, license creation, CSV bulk imports, session management and manual kicks.
  • Key files:
    • admin/src/modules/App.tsx — main admin application UI
    • admin/package.json — dev/build scripts and dependencies
    • admin/vite.config.ts, admin/tsconfig.json — build config
  • Typical dev commands:

cd admin
npm install
npm run dev      # start dev server (Vite)
npm run build    # produce production build

• workers/ — Cloudflare Workers backend (TypeScript)
  • Purpose: core license logic: Admin API, public license endpoints, policy engine, Ed25519 signing, ephemeral & feature tokens, floating seats via Durable Objects, D1 storage, KV config.
  • Key files & folders:
    • workers/src/index.ts — main request handler and API routes
    • workers/src/do/LicenseDO.ts — Durable Object for seat/heartbeat management
    • workers/migrations/0001_init.sql — D1 schema definitions (products, licenses, sessions, policies, fingerprints, tokens)
    • workers/wrangler.toml — Cloudflare configuration (D1, KV, Durable Objects bindings, env vars)
    • workers/README.md — (worker-specific quickstart)
  • Important environment/secrets:
    • SERVER_TIME_SECRET (secret) — HMAC secret used for server-time signing
    • ADMIN_JWT_PUBLIC_JWK (secret) — admin JWT verification public JWK
    • FEATURE_SCHEMA_STRICT (var) — optional strict feature schema enforcement
  • D1/KV/DO setup (example):

# create D1 database and KV namespace
wrangler d1 create licenseeye-db
wrangler kv:namespace create licenseeye

# apply migration (local or remote)
wrangler d1 migrations apply licenseeye-db --local
# or for production
wrangler d1 migrations apply licenseeye-db --remote

# deploy
cd workers
wrangler deploy

• sdk/ — TypeScript client SDK
  • Purpose: client-side helpers for heartbeats, validate/consume feature tokens, ephemeral token validation, storage adapter for quotas and last-seen server time, and policy handling.
  • Key files:
    • sdk/src/index.ts — SDK implementation (Ed25519 verification, consume logic)
    • sdk/package.json — build script
    • sdk/README.md — SDK usage examples (already included)
  • Build commands:

cd sdk
npm install
npm run build

• LICENSE — repository license text.
• .gitattributes — VCS attributes.

---

High-level concepts

• Products: contain a feature_schema (JSON schema-like) and per-product Ed25519 keypairs used for signing feature tokens.
• Licenses: associated with a product; can be perpetual, subscription, or floating (concurrent seats). Features on licenses are validated against product feature_schema (optionally strict).
• Sessions & Heartbeats: clients call a heartbeat endpoint that records session_id, machine_id, IP, and Cloudflare request.cf.country. Durable Objects enforce seat limits for floating licenses.
• Fingerprints & Risk Scoring: server aggregates machines_seen, country_changes, debug_hits, time_anomaly and avg_session_time to compute risk and transition license states (active → grace → restricted → revoked).
• Policies: hierarchical (global + product), merged at fetch time. Policies control soft-check probabilities, offline tolerance, delayed validation windows, and debug tolerances.
• Tokens:
  • Feature tokens: Ed25519-signed JSON granting feature access and quotas.
  • Ephemeral tokens: short-lived machine-bound tokens with TTL.
  • User tokens: client-signed tokens accepted by the license creation API.

---

Recommended local development flow

1. Start by creating D1 and KV, copy IDs into workers/wrangler.toml.
2. Set secrets locally (for dev you may put fallback keys in KV but prefer secrets):

wrangler secret put SERVER_TIME_SECRET
wrangler secret put ADMIN_JWT_PUBLIC_JWK

3. Apply DB migration locally:

wrangler d1 migrations apply licenseeye-db --local

4. Run the Workers dev server while developing:

cd workers
wrangler dev --local --persist

5. Run the Admin UI:

cd admin
npm install
npm run dev
# open browser at http://localhost:5173 (default Vite port)

6. Build SDK when you need to publish/use it in other projects:

cd sdk
npm install
npm run build

---

🏗️ Deployment Guide

1. Prepare Cloudflare Resources

# Login to Cloudflare
wrangler login

# Create D1 database and KV namespace
wrangler d1 create licenseeye-db
wrangler kv:namespace create licenseeye

# Copy the database_id and KV id into workers/wrangler.toml

2. Set Secrets

wrangler secret put SERVER_TIME_SECRET
wrangler secret put ADMIN_JWT_PUBLIC_JWK

3. Apply Database Migrations

cd workers
wrangler d1 migrations apply licenseeye-db --remote

4. Deploy Workers Backend

cd workers
wrangler deploy

5. Build and Deploy Admin UI

cd ../admin
npm install
npm run build
# Upload admin/dist/ to your static hosting (Cloudflare Pages, Vercel, etc.)

6. (Optional) Publish SDK to npm

See PUBLISHING.md for SDK publishing steps.

---

🛠️ Useful Commands

Dev server for Workers:

cd workers
wrangler dev --local --persist

Start admin UI:

cd admin
npm install
npm run dev

Build everything for release:

# workers deploy
cd workers
wrangler deploy

# admin production build
cd ../admin
npm run build

# sdk build
cd ../sdk
npm run build

---

Where to look for specific features

• Floating license/seat enforcement: workers/src/do/LicenseDO.ts
• DB schema and migrations: workers/migrations/0001_init.sql
• Feature token signing and verify flows: workers/src/index.ts (signing endpoints) and sdk/src/index.ts (verification/consume)
• Admin UI feature schema editing and CSV bulk: admin/src/modules/App.tsx
• Policy publishing and history: workers/src/index.ts (admin policy endpoints) and admin UI policy history components in admin/src/modules/App.tsx

---

Next Steps and Optional Improvements

• Add automated tests (unit/integration) for heartbeat, token verification, and DO seat management.
• Add CI to run TypeScript builds and linting for admin, workers, and sdk.
• Add a simple analytics dashboard for session/risk trends.
• Implement JWK rotation for admin JWTs and store JWK sets in KV.

---

📚 Additional Documentation

• QUICKSTART.md: Full setup and troubleshooting
• SECURITY.md: Security policy and best practices
• PUBLISHING.md: How to publish SDK and deploy to production

For questions or support, open an issue on GitHub.

• Add automated tests (unit/integration) for heartbeat, token verification, and DO seat management.
• Add CI to run TypeScript builds and linting for admin, workers, and sdk.
• Add a simple analytics dashboard for session/risk trends.
• Implement JWK rotation for admin JWTs and store JWK sets in KV.