webhanger 1.0.0 → 1.0.4

package/README.md

@@ -0,0 +1,594 @@
+# WebHanger
+
+> **Component-as-a-Service (CaaS)** — Bundle once. Encrypt with AES-256. Deliver via edge CDN. Load anywhere with zero code.
+
+WebHanger is a secure, edge-delivered component distribution platform. Think of it as npm for UI components — but instead of installing packages, you deploy encrypted components to a CDN and load them into any website with a single HTML tag.
+
+---
+
+## Packages
+
+| Package | Install | Description |
+|---|---|---|
+| `webhanger` | `npm install -g webhanger` | CLI + Node.js library |
+| `webhanger-front` | `npm install webhanger-front` | Browser SDK |
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install CLI
+npm install -g webhanger
+
+# 2. Setup your project (provisions S3 + CloudFront automatically)
+wh init
+
+# 3. Deploy all components, build site, zip for upload — one command
+wh ship ./components ./docs 1.0.0 ./dist
+```
+
+Load in any website — zero JS required:
+
+```html
+<script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
+<script>WebHangerFront.initialize("./wh-manifest.json");</script>
+
+<wh-component name="navbar"></wh-component>
+<wh-component name="hero"></wh-component>
+<wh-component name="footer"></wh-component>
+```
+
+---
+
+## CLI Reference
+
+### `wh init`
+
+Interactive project setup. Provisions infrastructure automatically.
+
+```bash
+wh init
+```
+
+Prompts:
+- Project name
+- Storage provider: `s3` | `r2` | `minio` | `local`
+- Database provider: `firebase` | `supabase` | `mongodb`
+- Credentials
+
+For **S3**: automatically creates the bucket, configures CORS + versioning, spins up a CloudFront distribution. No AWS Console needed.
+
+Optional: setup Cloudflare Edge Worker for token validation + geo routing at the edge.
+
+Generates `webhanger.config.json`.
+
+---
+
+### `wh ship` ⭐ The main command
+
+Deploy + build + zip in one shot.
+
+```bash
+wh ship <components-dir> <site-dir> [version] [out-dir]
+```
+
+```bash
+wh ship ./components ./docs 1.0.0 ./dist
+```
+
+What it does:
+1. Deploys all components (bundle → AES encrypt → upload → sign → register)
+2. Resolves dependency graph
+3. Writes `wh-manifest.json` (no sensitive data in HTML)
+4. Production builds the site (minify HTML, inline CSS/JS)
+5. Zips output for direct upload
+
+```
+🚀 [1/4] Deploying components...
+  navbar@1.0.0...    ✅
+  hero@1.0.0...      ✅
+
+🔍 [2/4] Resolving dependency graph...
+
+🏗️  [3/4] Building ./docs → ./dist...
+  index.html         4.2 kB
+
+📦 [4/4] Zipping ./dist...
+
+✅ Ship complete!
+  Deploy zip: ./deploy.zip (12.4 kB)
+```
+
+Upload `deploy.zip` to Netlify, S3, cPanel, or any static host.
+
+---
+
+### `wh deploy`
+
+Deploy a single component.
+
+```bash
+wh deploy <component-dir> <name> <version>
+wh deploy ./components/navbar navbar 1.0.0
+```
+
+Prompts for token (auto-generate or custom) and expiry (never or seconds).
+
+---
+
+### `wh graph-deploy`
+
+Deploy all components in a directory and resolve the dependency graph.
+
+```bash
+wh graph-deploy <components-dir> [version] [out-dir]
+wh graph-deploy ./components 1.0.0 ./output
+```
+
+---
+
+### `wh build`
+
+Production build — minifies HTML, inlines local CSS/JS.
+
+```bash
+wh build <src-dir> [out-dir]
+wh build ./docs ./dist
+```
+
+---
+
+### `wh zip`
+
+Zip a directory for deployment.
+
+```bash
+wh zip <src-dir> [out-file]
+wh zip ./dist ./deploy.zip
+```
+
+---
+
+### `wh analyze`
+
+Detect framework, styling approach, and CDN dependencies automatically.
+
+```bash
+wh analyze ./components/navbar
+```
+
+```
+🔍 Component Analysis
+
+Framework : vanilla
+Styling   : tailwind
+Imports   : gsap, axios
+CDN Assets:
+  [script] https://cdn.tailwindcss.com
+  [script] https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js
+```
+
+---
+
+### `wh convert`
+
+Convert a vanilla HTML/CSS/JS component to any framework.
+
+```bash
+wh convert <dir> <name> <target> [out-dir]
+wh convert ./components/navbar navbar react ./output
+```
+
+Supported targets: `react` `vue` `svelte` `next` `angular` `astro`
+
+---
+
+### `wh access`
+
+Role-based access control for teams.
+
+```bash
+wh access grant          # generate API key with role
+wh access revoke <key>   # revoke a key
+wh access list           # list all keys
+```
+
+Roles:
+
+| Role | deploy | read | delete | manage_access |
+|---|---|---|---|---|
+| owner | ✅ | ✅ | ✅ | ✅ |
+| admin | ✅ | ✅ | ✅ | ✅ |
+| deployer | ✅ | ✅ | ❌ | ❌ |
+| viewer | ❌ | ✅ | ❌ | ❌ |
+
+---
+
+### `wh edge-init`
+
+Setup Cloudflare Edge Worker for production-grade delivery.
+
+```bash
+wh edge-init
+# then:
+cd edge && wrangler deploy
+```
+
+---
+
+## Component Structure
+
+```
+components/
+  navbar/
+    index.html              ← markup
+    style.css               ← styles
+    script.js               ← behaviour
+    webhanger.component.json ← assets + dependencies
+```
+
+### `webhanger.component.json`
+
+```json
+{
+  "assets": [
+    { "type": "script", "url": "https://cdn.tailwindcss.com" },
+    { "type": "script", "url": "https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js" }
+  ],
+  "dependencies": ["navbar@1.0.0", "chart@2.0.0"]
+}
+```
+
+CDN assets are auto-detected by `wh analyze` and merged automatically on deploy.
+
+---
+
+## Dependency Graph
+
+npm-like dependency resolution for UI components.
+
+```
+dashboard@1.0.0
+  ├── navbar@1.0.0
+  └── statsbar@1.0.0
+        └── chart@1.0.0
+```
+
+- Depth-first resolution
+- Circular dependency detection with full chain error
+- Deps load before parent component
+- Stored in Firestore per project
+
+```bash
+wh graph-deploy ./components 1.0.0 ./output
+```
+
+Programmatic:
+
+```js
+import { resolveGraph } from "webhanger";
+const graph = await resolveGraph(config.db, projectId, "dashboard", "1.0.0");
+// Returns: [chart, navbar, statsbar, dashboard] — deps first
+```
+
+---
+
+## Security
+
+### AES-256-GCM Encryption
+
+Every component chunk (HTML/CSS/JS) is encrypted before upload.
+
+```
+Key     = SHA-256(projectId + salt)
+Payload = iv:tag:ciphertext  (base64)
+Salts   = "::html" | "::css" | "::js"
+```
+
+### HMAC-SHA256 Signed URLs
+
+```
+token = HMAC-SHA256(projectId:componentPath:expires, secretKey)
+```
+
+### Integrity Check
+
+SHA-256 hash of raw content stored in payload. Verified after decryption — detects tampering.
+
+### Domain Restriction
+
+```js
+WebHangerFront.load(url, pid, token, 0, "[data-wh]", null, [], {
+    allowedDomains: ["mysite.com", "app.io"]
+});
+```
+
+### Token Expiry
+
+```js
+// Never expires
+wh.deploy("./navbar", "navbar", "1.0.0");
+
+// Expires in 24 hours
+wh.deploy("./navbar", "navbar", "1.0.0", { expiresInSeconds: 86400 });
+```
+
+### Manifest-based Delivery
+
+Tokens, projectId, and CDN URLs never appear in HTML. Fetched at runtime from `wh-manifest.json`.
+
+---
+
+## Edge Worker (Cloudflare Workers)
+
+Runs at the edge before S3:
+
+- HMAC token validation
+- Version resolution (`latest` → `1.2.0` from KV)
+- Geo-based routing (India → ap-south-1, Europe → eu-west-1)
+- Rate limiting (100 req/min per IP)
+
+```bash
+wh init  # answer yes to edge worker setup
+cd edge && wrangler deploy
+```
+
+Update `cdn.url` in `webhanger.config.json` to your worker URL — all requests now go through the edge.
+
+---
+
+## Multi-CDN Failover
+
+```json
+{
+  "cdn": {
+    "url": "https://primary.cloudfront.net",
+    "fallbacks": [
+      "https://fallback.r2.dev",
+      "https://backup.b-cdn.net"
+    ]
+  }
+}
+```
+
+SDK tries each URL in order. If primary fails, automatically falls back — zero code changes needed.
+
+---
+
+## Browser SDK
+
+### Zero-code (recommended)
+
+```html
+<script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
+<script>WebHangerFront.initialize("./wh-manifest.json");</script>
+
+<wh-component name="navbar"></wh-component>
+<wh-component name="hero"></wh-component>
+<wh-component name="footer" sandbox></wh-component>
+```
+
+### Manual load
+
+```js
+WebHangerFront.load(
+    cdnUrl,      // string or array (multi-CDN)
+    projectId,   // decrypt key
+    token,       // HMAC token
+    expires,     // unix timestamp, 0 = never
+    selector,    // CSS selector, default "[data-wh]"
+    onSignal,    // optional signal callback
+    deps,        // optional pre-resolved deps array
+    options      // optional options object
+);
+```
+
+### Lifecycle hooks
+
+```js
+WebHangerFront.load(url, pid, token, 0, "[data-wh]", null, [], {
+    beforeMount: ({ html }) => showSpinner(),
+    afterMount:  ({ target }) => hideSpinner(),
+    onError:     (err) => showFallback(err),
+    sandbox:     true,                          // Shadow DOM isolation
+    allowedDomains: ["mysite.com"]              // domain restriction
+});
+```
+
+### Signal callback
+
+```js
+WebHangerFront.load(url, pid, token, 0, "[data-wh]", ({ stage, ...detail }) => {
+    // stages: start → fetching → assets → deps → injecting → done | error
+    console.log(stage, detail.time, detail.source);
+});
+```
+
+### Plugin system
+
+```js
+WebHangerFront.use({
+    install({ on, emit }) {
+        on("load",   ({ time, source }) => analytics.track("load", { time, source }));
+        on("error",  ({ message })      => errorTracker.capture(message));
+        on("metric", ({ name, value })  => dashboard.update(name, value));
+    }
+});
+```
+
+### Observability
+
+```js
+WebHangerFront.on("load",   ({ time, source }) => console.log(time, source));
+WebHangerFront.on("metric", ({ name, value })  => console.log(name, value));
+
+console.log(WebHangerFront.metrics);
+// { loads: 5, cacheHits: 3, errors: 0, totalTime: 420 }
+```
+
+### Hard flush
+
+```js
+await WebHangerFront.clearCache();
+// Clears: localStorage, IndexedDB, SW caches, sessionStorage, unregisters SW
+```
+
+---
+
+## Caching
+
+| Layer | Used for |
+|---|---|
+| `localStorage` | Components < 50KB |
+| `IndexedDB` | Components ≥ 50KB |
+| Service Worker | Offline fallback |
+
+**Stale-while-revalidate** — returns cached version instantly, refreshes in background.
+
+---
+
+## Node.js API
+
+```js
+import { WebHanger } from "webhanger";
+const wh = new WebHanger();
+
+// Deploy
+const result = await wh.deploy("./components/navbar", "navbar", "1.0.0", {
+    expiresInSeconds: 86400,   // optional
+    token: "custom-token",     // optional
+    dependencies: ["chart@1.0.0"]
+});
+// { cdnUrl, cdnUrls, token, expires, dependencies }
+
+// Resolve
+const comp = await wh.resolve("navbar", "1.0.0");
+
+// Rotate token without redeploying
+await wh.resign("navbar", "1.0.0", { expiresInSeconds: 3600 });
+
+// Delete from storage
+await wh.remove("navbar", "1.0.0");
+
+// Get config
+const config = wh.getConfig();
+```
+
+### Named exports
+
+```js
+import {
+    bundle, encrypt, decrypt, integrityHash,
+    signUrl, verifyToken, generateSecretKey,
+    upload, remove,
+    registerComponent, getComponent,
+    deploy, resolveGraph,
+    convert, analyzeComponent,
+    build,
+    grantAccess, revokeAccess, checkPermission, listAccess, generateApiKey,
+    provisionBucket, provisionCloudFront,
+    loadConfig
+} from "webhanger";
+```
+
+---
+
+## Storage Providers
+
+| Provider | Notes |
+|---|---|
+| `s3` | AWS S3 — auto-provisions bucket + CloudFront |
+| `r2` | Cloudflare R2 — zero egress fees |
+| `minio` | Self-hosted MinIO — S3-compatible |
+| `local` | Local disk — dev/testing only |
+
+## Database Providers
+
+| Provider | Notes |
+|---|---|
+| `firebase` | Firebase Firestore — free tier, real-time |
+| `supabase` | Supabase Postgres — open source |
+| `mongodb` | MongoDB Atlas — flexible documents |
+
+---
+
+## `webhanger.config.json`
+
+```json
+{
+  "project": "my-app",
+  "projectId": "wh_1234567890",
+  "secretKey": "64-char-hex-secret",
+  "webHangerVersion": "1.0.0",
+  "storage": {
+    "provider": "s3",
+    "accessKey": "...",
+    "secretKey": "...",
+    "bucket": "my-bucket",
+    "region": "ap-south-1",
+    "distributionId": "EXXXXX"
+  },
+  "cdn": {
+    "url": "https://primary.cloudfront.net",
+    "fallbacks": ["https://fallback.r2.dev"]
+  },
+  "db": {
+    "provider": "firebase",
+    "serviceAccountPath": "./firebase-service-account.json"
+  }
+}
+```
+
+> Keep this file private. Never commit it. Add to `.gitignore`.
+
+---
+
+## Architecture
+
+```
+Developer
+  └── wh ship ./components ./docs
+        ├── wh analyze    → detect Tailwind, GSAP, deps
+        ├── wh bundle     → html + css + js → single payload
+        ├── AES-256-GCM   → encrypt each chunk (SHA-256 key)
+        ├── SHA-256 hash  → integrity fingerprint
+        ├── S3 upload     → store encrypted payload
+        ├── HMAC sign     → project-scoped signed URL
+        ├── Firestore     → register metadata + dep graph
+        ├── wh build      → minify HTML, inline assets
+        └── wh zip        → deploy.zip ready for upload
+
+Browser
+  └── <wh-component name="navbar">
+        ├── fetch wh-manifest.json
+        ├── check token expiry
+        ├── stale-while-revalidate cache
+        ├── fetch from CloudFront (or Edge Worker)
+        │     └── Edge: validate token + geo route + rate limit
+        ├── multi-CDN failover if primary fails
+        ├── load CDN assets (Tailwind, GSAP, etc.)
+        ├── resolve + load dependency graph
+        ├── AES-256-GCM decrypt in memory
+        ├── SHA-256 integrity verify
+        ├── domain restriction check
+        ├── inject CSS → HTML → JS (or Shadow DOM)
+        ├── fire lifecycle hooks
+        └── emit metrics + plugin events
+```
+
+---
+
+## Real-World Use Cases
+
+- **Enterprise micro-frontends** — shared UI across 50+ apps, update once
+- **Education platforms** — push UI updates to all school sites instantly
+- **Low-bandwidth regions** — cache once, serve offline via Service Worker
+- **Security platforms** — inject warnings/banners dynamically across sites
+- **White-label SaaS** — per-tenant component customization
+
+---
+
+## License
+
+ISC