webhanger 1.0.6 → 1.0.9

package/bin/cli.js

@@ -345,70 +345,6 @@ switch (command) {
         console.log(chalk.gray(`  "cdn": { "url": "https://webhanger-edge.your-subdomain.workers.dev" }`));
         break;
     }
-    case "release": {
-        const releaseType = args[1] || "patch"; // patch | minor | major
-        const { execSync } = await import("child_process");
-        const { default: fsExtra } = await import("fs-extra");
-        const { default: pathMod } = await import("path");
-
-        console.log(chalk.cyan(`\n🚀 Releasing webhanger + webhanger-front (${releaseType})...\n`));
-
-        try {
-            // 1. Bump + publish webhanger
-            console.log(chalk.white("  [1/4] Publishing webhanger..."));
-            execSync(`npm version ${releaseType} --no-git-tag-version`, { stdio: "inherit" });
-            execSync("npm publish --access public", { stdio: "inherit" });
-            const whPkg = await fsExtra.readJson("./package.json");
-            console.log(chalk.green(`  ✅ webhanger@${whPkg.version} published`));
-
-            // 2. Build + bump + publish webhanger-front
-            console.log(chalk.white("\n  [2/4] Building webhanger-front..."));
-            execSync("npm run build", { cwd: "./webhanger-front", stdio: "inherit" });
-            execSync(`npm version ${releaseType} --no-git-tag-version`, { cwd: "./webhanger-front", stdio: "inherit" });
-            execSync("npm publish --access public", { cwd: "./webhanger-front", stdio: "inherit" });
-            const whfPkg = await fsExtra.readJson("./webhanger-front/package.json");
-            console.log(chalk.green(`  ✅ webhanger-front@${whfPkg.version} published`));
-
-            // 3. Update all HTML files to use new unpkg version
-            console.log(chalk.white("\n  [3/4] Updating unpkg references..."));
-            const newUrl = `https://unpkg.com/webhanger-front@${whfPkg.version}/browser.min.js`;
-            const oldPattern = /https:\/\/unpkg\.com\/webhanger-front@[^/]+\/browser(?:\.min)?\.js/g;
-
-            const htmlFiles = [];
-            async function findHtml(dir) {
-                const entries = await fsExtra.readdir(dir, { withFileTypes: true });
-                for (const e of entries) {
-                    if (e.name === "node_modules" || e.name === ".git") continue;
-                    const full = pathMod.join(dir, e.name);
-                    if (e.isDirectory()) await findHtml(full);
-                    else if (e.name.endsWith(".html") || e.name.endsWith(".js")) htmlFiles.push(full);
-                }
-            }
-            await findHtml(".");
-
-            let updated = 0;
-            for (const file of htmlFiles) {
-                const content = await fsExtra.readFile(file, "utf-8");
-                if (oldPattern.test(content)) {
-                    await fsExtra.writeFile(file, content.replace(oldPattern, newUrl), "utf-8");
-                    console.log(chalk.gray(`    → ${file}`));
-                    updated++;
-                }
-            }
-            console.log(chalk.green(`  ✅ Updated ${updated} files to ${newUrl}`));
-
-            // 4. Summary
-            console.log(chalk.green(`\n✅ Release complete!`));
-            console.log(chalk.white(`  webhanger        : v${whPkg.version}`));
-            console.log(chalk.white(`  webhanger-front  : v${whfPkg.version}`));
-            console.log(chalk.gray(`  unpkg URL        : ${newUrl}\n`));
-
-        } catch (err) {
-            console.log(chalk.red(`\n❌ Release failed: ${err.message}`));
-            process.exit(1);
-        }
-        break;
-    }
     case "atomize": {
         const atomFile = args[1];
         const atomOut  = args[2] || "./atomized";
@@ -460,11 +396,9 @@ switch (command) {
         const manifestPath = pathMod.join(pathMod.dirname(atomFile), "wh-manifest.json");
         await fsExtra.writeJson(manifestPath, manifest, { spaces: 2 });
 
-        // Step 4: Write globalJs to a separate file to avoid template literal conflicts
+        // Step 4: Write globalJs to separate file
         const globalJsFile = pathMod.join(pathMod.dirname(atomFile), "wh-global.js");
-        if (globalJs) {
-            await fsExtra.writeFile(globalJsFile, globalJs, "utf-8");
-        }
+        if (globalJs) await fsExtra.writeFile(globalJsFile, globalJs, "utf-8");
 
         // Step 5: Generate production-ready CDN-powered HTML
         const mounts = components.map(c => `  <wh-component name="${c.name}"></wh-component>`).join("\n");
@@ -475,15 +409,24 @@ switch (command) {
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>WebHanger</title>
   ${cdnAssets.filter(a => a.type === "style").map(a => `<link rel="stylesheet" href="${a.url}">`).join("\n  ")}
+  <script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
 </head>
 <body>
 ${mounts}
   ${cdnAssets.filter(a => a.type === "script").map(a => `<script src="${a.url}"></script>`).join("\n  ")}
-  <script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
   <script>
+    var totalComponents = document.querySelectorAll("wh-component").length;
+    var mountedCount = 0;
+    WebHangerFront.on("afterMount", function() {
+      mountedCount++;
+      if (mountedCount >= totalComponents && !window.__whGlobalRan) {
+        window.__whGlobalRan = true;
+        ${globalJs ? `var s = document.createElement("script"); s.src = "./wh-global.js"; document.body.appendChild(s);` : ""}
+      }
+    });
     WebHangerFront.initialize("./wh-manifest.json");
   </script>
-  ${globalJs ? `<script src="./wh-global.js"></script>` : ""}
+  ${globalJs ? "" : ""}
 </body>
 </html>`;
 
@@ -517,6 +460,259 @@ ${mounts}
         }
         break;
     }
+    case "personalize": {
+        const { default: fsExtra } = await import("fs-extra");
+        const { default: pathMod } = await import("path");
+
+        const subCmd = args[1];
+
+        if (subCmd === "init") {
+            // Scaffold a wh-personalization.json
+            const example = {
+                hero: {
+                    rules: [
+                        { if: { country: "IN" },       component: "hero-india"   },
+                        { if: { country: "US" },       component: "hero-us"      },
+                        { if: { device: "mobile" },    component: "hero-mobile"  },
+                        { if: { role: "premium" },     component: "hero-premium" },
+                        { if: { abTest: "variant-b" }, component: "hero-b"       }
+                    ],
+                    default: "hero"
+                },
+                navbar: {
+                    rules: [
+                        { if: { role: "admin" },   component: "navbar-admin"   },
+                        { if: { plan: "premium" }, component: "navbar-premium" }
+                    ],
+                    default: "navbar"
+                }
+            };
+            const dest = pathMod.join(process.cwd(), "wh-personalization.json");
+            await fsExtra.writeJson(dest, example, { spaces: 2 });
+            console.log(chalk.green("\n✅ wh-personalization.json created"));
+            console.log(chalk.gray("  Edit the rules to match your use case."));
+            console.log(chalk.gray("  Supported conditions: country, device, role, abTest, lang, hour, plan\n"));
+
+        } else if (subCmd === "test") {
+            // Test rule resolution against current context
+            const { resolveAll } = await import("../helper/personalization.js");
+            const configPath = args[2] || "./wh-personalization.json";
+            if (!fsExtra.existsSync(configPath)) {
+                console.log(chalk.red(`${configPath} not found. Run: wh personalize init`));
+                process.exit(1);
+            }
+            const config = await fsExtra.readJson(configPath);
+            const country = args[3] || "US";
+            const device  = args[4] || "desktop";
+            const role    = args[5] || null;
+
+            const { resolved, ctx } = resolveAll(config, { country, device, role });
+
+            console.log(chalk.cyan("\n🎯 Personalization Resolution\n"));
+            console.log(chalk.white("Context:"));
+            console.log(chalk.gray(`  country : ${ctx.country || "—"}`));
+            console.log(chalk.gray(`  device  : ${ctx.device}`));
+            console.log(chalk.gray(`  role    : ${ctx.role || "—"}`));
+            console.log(chalk.gray(`  abTest  : ${ctx.abTest}`));
+            console.log(chalk.gray(`  lang    : ${ctx.lang}`));
+            console.log(chalk.gray(`  plan    : ${ctx.plan}`));
+            console.log(chalk.white("\nResolved components:"));
+            for (const [slot, comp] of Object.entries(resolved)) {
+                console.log(chalk.gray(`  ${slot.padEnd(15)} → ${comp}`));
+            }
+            console.log();
+
+        } else {
+            console.log(chalk.white("wh personalize commands:"));
+            console.log(chalk.gray("  wh personalize init                          — scaffold wh-personalization.json"));
+            console.log(chalk.gray("  wh personalize test [config] [country] [device] [role]  — test rule resolution"));
+        }
+        break;
+    }
+    case "auth": {
+        const authSubCmd = args[1];
+
+        if (authSubCmd === "init") {
+            // ── wh auth init ──────────────────────────────────────────────────
+            console.log(chalk.cyan("\n🔐 WebHanger Auth Setup\n"));
+
+            const { loadAuthConfig: _l, saveAuthConfig, generateSessionSecret, buildCallbackUrl, PROVIDERS } = await import("../helper/authConfig.js");
+
+            const providerChoices = [
+                { name: "Google",   value: "google",   checked: true },
+                { name: "GitHub",   value: "github",   checked: true },
+                { name: "Facebook", value: "facebook", checked: false }
+            ];
+
+            const answers = await inquirer.prompt([
+                {
+                    type: "checkbox",
+                    name: "providers",
+                    message: "Select OAuth providers:",
+                    choices: providerChoices,
+                    validate: v => v.length > 0 || "Select at least one provider"
+                },
+                {
+                    type: "input",
+                    name: "baseUrl",
+                    message: "Your app base URL (e.g. https://myapp.com):",
+                    validate: v => v.startsWith("http") || "Must be a valid URL"
+                },
+                {
+                    type: "input",
+                    name: "callbackPath",
+                    message: "OAuth callback path:",
+                    default: "/auth/callback"
+                },
+                {
+                    type: "input",
+                    name: "port",
+                    message: "Auth server port:",
+                    default: "3001"
+                }
+            ]);
+
+            const config = {
+                baseUrl:      answers.baseUrl.replace(/\/$/, ""),
+                callbackPath: answers.callbackPath,
+                port:         parseInt(answers.port),
+                providers:    {},
+                session: {
+                    secret:    generateSessionSecret(),
+                    expiresIn: "7d"
+                }
+            };
+
+            // Collect credentials per provider
+            for (const provider of answers.providers) {
+                console.log(chalk.cyan(`\n⚙️  Configure ${provider.charAt(0).toUpperCase() + provider.slice(1)}`));
+                const cbUrl = buildCallbackUrl(answers.baseUrl, answers.callbackPath, provider, answers.port);
+                console.log(chalk.gray(`  Callback URL: ${cbUrl}`));
+
+                const links = {
+                    google:   "https://console.cloud.google.com/apis/credentials",
+                    github:   "https://github.com/settings/developers",
+                    facebook: "https://developers.facebook.com/apps"
+                };
+                console.log(chalk.gray(`  Create app at: ${links[provider]}\n`));
+
+                const creds = await inquirer.prompt([
+                    { type: "input",    name: "clientId",     message: `${provider} Client ID:` },
+                    { type: "password", name: "clientSecret", message: `${provider} Client Secret:` }
+                ]);
+
+                config.providers[provider] = {
+                    clientId:     creds.clientId,
+                    clientSecret: creds.clientSecret,
+                    scopes:       PROVIDERS[provider].scopes,
+                    callbackUrl:  cbUrl
+                };
+            }
+
+            const dest = await saveAuthConfig(config);
+            console.log(chalk.green(`\n✅ wh-auth.config.json created`));
+            console.log(chalk.white("\n📋 Add these callback URLs to your OAuth apps:"));
+            for (const [p, c] of Object.entries(config.providers)) {
+                console.log(chalk.gray(`  ${p.padEnd(10)} → ${c.callbackUrl}`));
+            }
+            console.log(chalk.cyan(`\n▶  Start auth server: wh auth serve\n`));
+
+        } else if (authSubCmd === "serve") {
+            // ── wh auth serve ─────────────────────────────────────────────────
+            const { loadAuthConfig } = await import("../helper/authConfig.js");
+            const { buildAuthUrl, exchangeCode, fetchProfile, issueJWT, generateState } = await import("../helper/oauthHandler.js");
+            const http = await import("http");
+
+            const authConfig = loadAuthConfig();
+            const PORT = args[2] ? parseInt(args[2]) : authConfig.port || 3001;
+            const states = new Map(); // CSRF state store
+
+            const server = http.default.createServer(async (req, res) => {
+                const url = new URL(req.url, `http://localhost:${PORT}`);
+                const p   = url.pathname;
+
+                // ── Initiate OAuth ────────────────────────────────────────────
+                const initMatch = p.match(/^\/auth\/([a-z]+)$/);
+                if (initMatch) {
+                    const provider = initMatch[1];
+                    if (!authConfig.providers[provider]) { res.writeHead(404); res.end("Provider not configured"); return; }
+                    const state = generateState();
+                    states.set(state, { provider, ts: Date.now() });
+                    const authUrl = buildAuthUrl(provider, authConfig, state);
+                    res.writeHead(302, { Location: authUrl });
+                    res.end(); return;
+                }
+
+                // ── OAuth callback ────────────────────────────────────────────
+                const cbMatch = p.match(/^\/auth\/callback\/([a-z]+)$/);
+                if (cbMatch) {
+                    const provider = cbMatch[1];
+                    const code     = url.searchParams.get("code");
+                    const state    = url.searchParams.get("state");
+
+                    if (!states.has(state)) { res.writeHead(400); res.end("Invalid state"); return; }
+                    states.delete(state);
+
+                    try {
+                        const accessToken = await exchangeCode(provider, code, authConfig);
+                        const user        = await fetchProfile(provider, accessToken);
+                        const jwt         = issueJWT(user, authConfig.session.secret, authConfig.session.expiresIn);
+
+                        // Return HTML that posts token back to opener or redirects
+                        res.writeHead(200, { "Content-Type": "text/html" });
+                        res.end(`<!DOCTYPE html><html><body><script>
+                            var user = ${JSON.stringify(user)};
+                            var token = "${jwt}";
+                            localStorage.setItem("wh_auth_token", token);
+                            localStorage.setItem("wh_auth_user", JSON.stringify(user));
+                            if (window.opener) {
+                                window.opener.postMessage({ type: "WH_AUTH_SUCCESS", user, token }, "*");
+                                window.close();
+                            } else {
+                                var redirect = sessionStorage.getItem("wh_auth_redirect") || "/";
+                                window.location.href = redirect.replace("{{email}}", encodeURIComponent(user.email)).replace("{{name}}", encodeURIComponent(user.name));
+                            }
+                        </script></body></html>`);
+                    } catch (err) {
+                        res.writeHead(200, { "Content-Type": "text/html" });
+                        res.end(`<!DOCTYPE html><html><body><script>
+                            if (window.opener) {
+                                window.opener.postMessage({ type: "WH_AUTH_ERROR", message: "${err.message}" }, "*");
+                                window.close();
+                            } else { document.body.innerText = "Auth error: ${err.message}"; }
+                        </script></body></html>`);
+                    }
+                    return;
+                }
+
+                // ── Health check ──────────────────────────────────────────────
+                if (p === "/health") {
+                    res.writeHead(200, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" });
+                    res.end(JSON.stringify({ ok: true, providers: Object.keys(authConfig.providers) }));
+                    return;
+                }
+
+                res.writeHead(404); res.end("Not found");
+            });
+
+            server.listen(PORT, () => {
+                console.log(chalk.cyan(`\n🔐 WebHanger Auth Server\n`));
+                console.log(chalk.white(`  Listening : http://localhost:${PORT}`));
+                console.log(chalk.gray(`  Providers : ${Object.keys(authConfig.providers).join(", ")}`));
+                console.log(chalk.gray(`\n  OAuth URLs:`));
+                for (const provider of Object.keys(authConfig.providers)) {
+                    console.log(chalk.gray(`    http://localhost:${PORT}/auth/${provider}`));
+                }
+                console.log();
+            });
+
+        } else {
+            console.log(chalk.white("wh auth commands:"));
+            console.log(chalk.gray("  wh auth init          — setup OAuth providers"));
+            console.log(chalk.gray("  wh auth serve [port]  — start OAuth callback server"));
+        }
+        break;
+    }
     case "access": {
         const subCmd = args[1]; // grant | revoke | list
         const loadConfigFn = (await import("../helper/loadConfig.js")).default;
@@ -924,7 +1120,6 @@ ${mounts}
         console.log(chalk.cyan(BANNER));
         console.log(chalk.white("Commands:"));
         console.log(chalk.gray("  wh init                                              — setup your project"));
-        console.log(chalk.gray("  wh release [patch|minor|major]                       — publish both packages + update all unpkg refs"));
         console.log(chalk.gray("  wh ship <comp-dir> <site-dir> [version] [out-dir]    — deploy + build + zip in one shot"));
         console.log(chalk.gray("  wh deploy <dir> <name> <version>                     — deploy a single component"));
         console.log(chalk.gray("  wh graph-deploy <comp-dir> [version] [out-dir]       — deploy all + resolve dep graph"));

package/helper/authConfig.js

@@ -0,0 +1,68 @@
+import fs from "fs-extra";
+import path from "path";
+import crypto from "crypto";
+
+const CONFIG_FILE = "wh-auth.config.json";
+
+export const PROVIDERS = {
+    google: {
+        authUrl:    "https://accounts.google.com/o/oauth2/v2/auth",
+        tokenUrl:   "https://oauth2.googleapis.com/token",
+        profileUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
+        scopes:     ["openid", "email", "profile"],
+        fields:     ["id", "email", "name", "picture"]
+    },
+    github: {
+        authUrl:    "https://github.com/login/oauth/authorize",
+        tokenUrl:   "https://github.com/login/oauth/access_token",
+        profileUrl: "https://api.github.com/user",
+        emailUrl:   "https://api.github.com/user/emails",
+        scopes:     ["user:email", "read:user"],
+        fields:     ["id", "email", "name", "avatar_url", "login"]
+    },
+    facebook: {
+        authUrl:    "https://www.facebook.com/v18.0/dialog/oauth",
+        tokenUrl:   "https://graph.facebook.com/v18.0/oauth/access_token",
+        profileUrl: "https://graph.facebook.com/me",
+        scopes:     ["email", "public_profile"],
+        fields:     ["id", "email", "name", "picture"]
+    }
+};
+
+export function loadAuthConfig(configPath = null) {
+    const candidates = [
+        configPath,
+        path.join(process.cwd(), CONFIG_FILE),
+    ].filter(Boolean);
+
+    for (const c of candidates) {
+        if (fs.existsSync(c)) return fs.readJsonSync(c);
+    }
+    throw new Error(`${CONFIG_FILE} not found. Run: wh auth init`);
+}
+
+export async function saveAuthConfig(config, configPath = null) {
+    const dest = configPath || path.join(process.cwd(), CONFIG_FILE);
+    await fs.writeJson(dest, config, { spaces: 2 });
+    return dest;
+}
+
+export function generateSessionSecret() {
+    return crypto.randomBytes(32).toString("hex");
+}
+
+export function buildCallbackUrl(baseUrl, callbackPath, provider, port = null) {
+    let base = baseUrl.replace(/\/$/, "");
+
+    // If port is provided and not already in the URL, inject it
+    if (port) {
+        try {
+            const u = new URL(base);
+            if (!u.port) u.port = String(port);
+            base = u.origin;
+        } catch (_) {}
+    }
+
+    const cb = callbackPath.replace(/\/$/, "");
+    return `${base}${cb}/${provider}`;
+}

package/helper/bundler.js

@@ -49,13 +49,14 @@ export async function bundle(componentDir, projectId) {
     const encryptChunk = (content, salt) => encrypt(content, projectId, salt);
 
     const payload = {
-        v: 2,                                    // version 2 = AES encrypted
+        v: 2,
         h: encryptChunk(html, "::html"),
         c: encryptChunk(css,  "::css"),
         j: encryptChunk(js,   "::js"),
         assets: meta.assets || [],
         dependencies: meta.dependencies || [],
-        integrity: integrityHash(html + css + js) // tamper detection
+        props: meta.props || {},
+        integrity: integrityHash(html + css + js)
     };
 
     return JSON.stringify(payload);

package/helper/dbHandler.js

@@ -31,10 +31,17 @@ function getFirestore(serviceAccountPath) {
 
 async function firebaseRegister(db, projectId, meta) {
     const { name, version, cdnUrl, token, expires, dependencies = [] } = meta;
-    await db
-        .collection("projects").doc(projectId)
-        .collection("components").doc(name)
-        .collection("versions").doc(version)
+
+    // Ensure parent project document exists (required for Firestore queries)
+    const projectRef = db.collection("projects").doc(projectId);
+    await projectRef.set({ projectId, updatedAt: admin.firestore.FieldValue.serverTimestamp() }, { merge: true });
+
+    // Ensure component document exists
+    const compRef = projectRef.collection("components").doc(name);
+    await compRef.set({ name, updatedAt: admin.firestore.FieldValue.serverTimestamp() }, { merge: true });
+
+    // Write version
+    await compRef.collection("versions").doc(version)
         .set({ name, version, cdnUrl, token, expires, dependencies, createdAt: admin.firestore.FieldValue.serverTimestamp() });
 }
 

package/helper/oauthHandler.js

@@ -0,0 +1,149 @@
+import crypto from "crypto";
+import { PROVIDERS } from "./authConfig.js";
+
+/**
+ * Build the OAuth redirect URL for a provider.
+ */
+export function buildAuthUrl(provider, config, state) {
+    const p = PROVIDERS[provider];
+    const providerConfig = config.providers[provider];
+    if (!p || !providerConfig) throw new Error(`Provider "${provider}" not configured.`);
+
+    const params = new URLSearchParams({
+        client_id:     providerConfig.clientId,
+        redirect_uri:  providerConfig.callbackUrl,
+        response_type: "code",
+        scope:         p.scopes.join(" "),
+        state
+    });
+
+    if (provider === "google") params.set("access_type", "offline");
+
+    return `${p.authUrl}?${params.toString()}`;
+}
+
+/**
+ * Exchange authorization code for access token.
+ */
+export async function exchangeCode(provider, code, config) {
+    const p = PROVIDERS[provider];
+    const providerConfig = config.providers[provider];
+
+    const body = new URLSearchParams({
+        client_id:     providerConfig.clientId,
+        client_secret: providerConfig.clientSecret,
+        code,
+        redirect_uri:  providerConfig.callbackUrl,
+        grant_type:    "authorization_code"
+    });
+
+    const res = await fetch(p.tokenUrl, {
+        method:  "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json" },
+        body:    body.toString()
+    });
+
+    const data = await res.json();
+    if (data.error) throw new Error(`Token exchange failed: ${data.error_description || data.error}`);
+    return data.access_token;
+}
+
+/**
+ * Fetch user profile from provider.
+ */
+export async function fetchProfile(provider, accessToken) {
+    const p = PROVIDERS[provider];
+
+    const res = await fetch(
+        provider === "facebook"
+            ? `${p.profileUrl}?fields=${p.fields.join(",")}&access_token=${accessToken}`
+            : p.profileUrl,
+        { headers: { Authorization: `Bearer ${accessToken}`, "User-Agent": "WebHanger-Auth/1.0" } }
+    );
+
+    const profile = await res.json();
+
+    // GitHub: email may need separate request
+    if (provider === "github" && !profile.email) {
+        const emailRes = await fetch(p.emailUrl, {
+            headers: { Authorization: `Bearer ${accessToken}`, "User-Agent": "WebHanger-Auth/1.0" }
+        });
+        const emails = await emailRes.json();
+        const primary = emails.find(e => e.primary && e.verified);
+        if (primary) profile.email = primary.email;
+    }
+
+    // Normalize profile across providers
+    return normalizeProfile(provider, profile);
+}
+
+function normalizeProfile(provider, raw) {
+    switch (provider) {
+        case "google":
+            return {
+                id:       raw.id,
+                email:    raw.email,
+                name:     raw.name,
+                avatar:   raw.picture,
+                provider: "google"
+            };
+        case "github":
+            return {
+                id:       String(raw.id),
+                email:    raw.email || "",
+                name:     raw.name || raw.login,
+                avatar:   raw.avatar_url,
+                username: raw.login,
+                provider: "github"
+            };
+        case "facebook":
+            return {
+                id:       raw.id,
+                email:    raw.email || "",
+                name:     raw.name,
+                avatar:   raw.picture?.data?.url || "",
+                provider: "facebook"
+            };
+        default:
+            return { ...raw, provider };
+    }
+}
+
+/**
+ * Issue a signed JWT for the user.
+ */
+export function issueJWT(user, sessionSecret, expiresIn = "7d") {
+    const header  = btoa(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+    const exp     = Math.floor(Date.now() / 1000) + parseDuration(expiresIn);
+    const payload = btoa(JSON.stringify({ ...user, exp, iat: Math.floor(Date.now() / 1000) }));
+    const sig     = crypto.createHmac("sha256", sessionSecret)
+                          .update(`${header}.${payload}`).digest("base64url");
+    return `${header}.${payload}.${sig}`;
+}
+
+/**
+ * Verify and decode a JWT.
+ */
+export function verifyJWT(token, sessionSecret) {
+    const [header, payload, sig] = token.split(".");
+    const expected = crypto.createHmac("sha256", sessionSecret)
+                           .update(`${header}.${payload}`).digest("base64url");
+    if (sig !== expected) throw new Error("Invalid token signature.");
+    const data = JSON.parse(Buffer.from(payload, "base64").toString("utf-8"));
+    if (data.exp && Date.now() / 1000 > data.exp) throw new Error("Token expired.");
+    return data;
+}
+
+function parseDuration(str) {
+    const units = { s: 1, m: 60, h: 3600, d: 86400 };
+    const match = str.match(/^(\d+)([smhd])$/);
+    if (!match) return 604800; // default 7d
+    return parseInt(match[1]) * (units[match[2]] || 1);
+}
+
+/**
+ * Generate a random state token for CSRF protection.
+ */
+export function generateState() {
+    return crypto.randomBytes(16).toString("hex");
+}