hanzi-browse 2.2.0

package/dist/managed/api.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tests for Managed API
+ *
+ * Covers:
+ * - Browser session pairing/registration lifecycle
+ * - Workspace ownership enforcement on tasks
+ * - Session connectivity validation
+ * - Unauthorized access (wrong workspace, missing auth)
+ */
+export {};

package/dist/managed/api.test.js

@@ -0,0 +1,146 @@
+/**
+ * Tests for Managed API
+ *
+ * Covers:
+ * - Browser session pairing/registration lifecycle
+ * - Workspace ownership enforcement on tasks
+ * - Session connectivity validation
+ * - Unauthorized access (wrong workspace, missing auth)
+ */
+import { createWorkspace, createApiKey, createPairingToken, consumePairingToken, getBrowserSession, validateSessionToken, createTaskRun, getTaskRun, listTaskRuns, recordUsage, getUsageSummary, } from "./store.js";
+let wsA;
+let wsB;
+let keyA;
+let keyB;
+function setup() {
+    wsA = createWorkspace("Workspace A");
+    wsB = createWorkspace("Workspace B");
+    keyA = createApiKey(wsA.id, "key-a");
+    keyB = createApiKey(wsB.id, "key-b");
+}
+function assert(condition, msg) {
+    if (!condition)
+        throw new Error(`FAIL: ${msg}`);
+    console.log(`  ✓ ${msg}`);
+}
+// --- Test: Pairing Token Lifecycle ---
+function testPairingTokenLifecycle() {
+    console.log("\n--- Pairing Token Lifecycle ---");
+    // Create pairing token from workspace A
+    const pt = createPairingToken(wsA.id, keyA.id);
+    assert(pt._plainToken.startsWith("hic_pair_"), "Pairing token has correct prefix");
+    assert(pt.workspaceId === wsA.id, "Pairing token bound to workspace A");
+    assert(!pt.consumed, "Pairing token not yet consumed");
+    assert(pt.expiresAt > Date.now(), "Pairing token not expired");
+    // Consume it using the plaintext token — creates a browser session
+    const session = consumePairingToken(pt._plainToken);
+    assert(session !== null, "Session created from pairing token");
+    assert(session.workspaceId === wsA.id, "Session inherits workspace from pairing token");
+    assert(session.sessionToken.startsWith("hic_sess_"), "Session token has correct prefix");
+    assert(session.status === "connected", "Session starts as connected");
+    // Cannot consume again
+    const session2 = consumePairingToken(pt._plainToken);
+    assert(session2 === null, "Cannot consume pairing token twice");
+    // Invalid token returns null
+    const session3 = consumePairingToken("hic_pair_bogus");
+    assert(session3 === null, "Invalid pairing token returns null");
+}
+// --- Test: Session Token Validation ---
+function testSessionTokenValidation() {
+    console.log("\n--- Session Token Validation ---");
+    const pt = createPairingToken(wsA.id, keyA.id);
+    const session = consumePairingToken(pt._plainToken);
+    // Valid session token (session.sessionToken is plaintext from consumePairingToken)
+    const validated = validateSessionToken(session.sessionToken);
+    assert(validated !== null, "Valid session token validates");
+    assert(validated.id === session.id, "Validated session has correct ID");
+    assert(validated.workspaceId === wsA.id, "Validated session has correct workspace");
+    // Invalid session token
+    const invalid = validateSessionToken("hic_sess_bogus");
+    assert(invalid === null, "Invalid session token returns null");
+}
+// --- Test: Workspace Ownership on Tasks ---
+function testWorkspaceOwnership() {
+    console.log("\n--- Workspace Ownership ---");
+    // Create a task in workspace A
+    const task = createTaskRun({
+        workspaceId: wsA.id,
+        apiKeyId: keyA.id,
+        task: "test task",
+        browserSessionId: "session-1",
+    });
+    // Workspace A can see it
+    const fromA = getTaskRun(task.id);
+    assert(fromA !== null, "Task exists");
+    assert(fromA.workspaceId === wsA.id, "Task belongs to workspace A");
+    // List tasks for workspace A includes it
+    const listA = listTaskRuns(wsA.id);
+    assert(listA.some((t) => t.id === task.id), "Workspace A list includes the task");
+    // List tasks for workspace B does NOT include it
+    const listB = listTaskRuns(wsB.id);
+    assert(!listB.some((t) => t.id === task.id), "Workspace B list does NOT include the task");
+    // Cross-workspace check
+    const crossCheck = getTaskRun(task.id);
+    assert(crossCheck.workspaceId !== wsB.id, "Task workspace does not match workspace B");
+}
+// --- Test: Session Must Belong to Workspace ---
+function testSessionWorkspaceBinding() {
+    console.log("\n--- Session Workspace Binding ---");
+    // Create session in workspace A via pairing token
+    const ptA = createPairingToken(wsA.id, keyA.id);
+    const sessionA = consumePairingToken(ptA._plainToken);
+    // Session belongs to workspace A
+    assert(sessionA.workspaceId === wsA.id, "Session belongs to workspace A");
+    // Create session in workspace B
+    const ptB = createPairingToken(wsB.id, keyB.id);
+    const sessionB = consumePairingToken(ptB._plainToken);
+    assert(sessionB.workspaceId === wsB.id, "Session belongs to workspace B");
+    // Workspace A cannot use workspace B's session for task creation
+    // (The API enforces this — we test the data model here)
+    const sessionFromStore = getBrowserSession(sessionB.id);
+    assert(sessionFromStore.workspaceId !== wsA.id, "Workspace A cannot claim workspace B's session");
+}
+// --- Test: Pairing Token Expiry ---
+function testPairingTokenExpiry() {
+    console.log("\n--- Pairing Token Expiry ---");
+    // Test that a nonexistent/invalid token returns null (covers the expired path)
+    const session = consumePairingToken("hic_pair_this_token_does_not_exist_at_all");
+    assert(session === null, "Invalid/nonexistent pairing token cannot be consumed");
+}
+// --- Test: Usage Attribution ---
+function testUsageAttribution() {
+    console.log("\n--- Usage Attribution ---");
+    const task = createTaskRun({
+        workspaceId: wsA.id,
+        apiKeyId: keyA.id,
+        task: "usage test",
+    });
+    recordUsage({
+        workspaceId: wsA.id,
+        apiKeyId: keyA.id,
+        taskRunId: task.id,
+        inputTokens: 10000,
+        outputTokens: 500,
+        apiCalls: 5,
+        model: "gemini-2.5-flash",
+    });
+    const summaryA = getUsageSummary(wsA.id);
+    assert(summaryA.totalInputTokens >= 10000, "Usage attributed to workspace A");
+    assert(summaryA.totalApiCalls >= 5, "API calls attributed to workspace A");
+    assert(summaryA.totalCostUsd > 0, "Cost calculated");
+    const summaryB = getUsageSummary(wsB.id);
+    assert(summaryB.totalInputTokens === 0, "Workspace B has no usage");
+}
+// --- Run all ---
+function runAll() {
+    console.log("=== Managed API Tests ===");
+    setup();
+    testPairingTokenLifecycle();
+    testSessionTokenValidation();
+    testWorkspaceOwnership();
+    testSessionWorkspaceBinding();
+    testPairingTokenExpiry();
+    testUsageAttribution();
+    console.log("\n=== All tests passed ===\n");
+}
+runAll();

package/dist/managed/auth.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Better Auth Configuration
+ *
+ * Human auth for the managed platform.
+ * - Google sign-in (default)
+ * - Email/password (fallback)
+ * - Session management
+ * - Linked to Hanzi workspace model
+ *
+ * Better Auth handles: user accounts, sessions, OAuth.
+ * Hanzi handles: workspaces, API keys, browser sessions, tasks, billing.
+ */
+export declare function createAuth(): any;
+/**
+ * Resolve a Better Auth session cookie to workspace info.
+ * Returns { userId, workspaceId } or null.
+ * Uses direct DB lookup (same reason as resolveSessionProfile).
+ */
+export declare function resolveSessionToWorkspace(req: import("http").IncomingMessage): Promise<{
+    userId: string;
+    workspaceId: string;
+} | null>;
+/**
+ * Resolve session to full profile (user name, email, workspace name).
+ * Used by GET /v1/me for the developer console.
+ *
+ * Uses direct DB lookup instead of auth.api.getSession() because
+ * Better Auth's cookie reading fails behind Caddy reverse proxy
+ * (cookie prefix mismatch between set and read paths).
+ */
+export declare function resolveSessionProfile(req: import("http").IncomingMessage): Promise<{
+    userId: string;
+    workspaceId: string;
+    userName: string;
+    userEmail: string;
+    workspaceName: string;
+    plan: string;
+} | null>;

package/dist/managed/auth.js

@@ -0,0 +1,192 @@
+/**
+ * Better Auth Configuration
+ *
+ * Human auth for the managed platform.
+ * - Google sign-in (default)
+ * - Email/password (fallback)
+ * - Session management
+ * - Linked to Hanzi workspace model
+ *
+ * Better Auth handles: user accounts, sessions, OAuth.
+ * Hanzi handles: workspaces, API keys, browser sessions, tasks, billing.
+ */
+import { betterAuth } from "better-auth";
+import pg from "pg";
+import { log } from "./log.js";
+const { Pool } = pg;
+const DATABASE_URL = process.env.DATABASE_URL || "";
+// Shared pool for workspace provisioning queries (separate from Better Auth's pool)
+let provisionPool = null;
+function getProvisionPool() {
+    if (!provisionPool) {
+        provisionPool = new Pool({ connectionString: DATABASE_URL, max: 3 });
+    }
+    return provisionPool;
+}
+// Singleton — created once, reused across all requests
+let authInstance = null;
+let authInitialized = false;
+export function createAuth() {
+    if (authInitialized)
+        return authInstance;
+    authInitialized = true;
+    if (!DATABASE_URL) {
+        log.info("No DATABASE_URL — Better Auth disabled");
+        return null;
+    }
+    const authSecret = process.env.BETTER_AUTH_SECRET;
+    if (!authSecret) {
+        if (process.env.NODE_ENV === "production") {
+            log.error("FATAL: BETTER_AUTH_SECRET not set — sessions lost on restart");
+            process.exit(1);
+        }
+        log.warn("BETTER_AUTH_SECRET not set — sessions invalidated on restart");
+    }
+    authInstance = betterAuth({
+        database: new Pool({ connectionString: DATABASE_URL, max: 5 }),
+        secret: authSecret,
+        baseURL: process.env.BETTER_AUTH_URL || "https://api.hanzilla.co",
+        emailAndPassword: {
+            enabled: true,
+        },
+        socialProviders: {
+            google: {
+                clientId: process.env.GOOGLE_CLIENT_ID || "",
+                clientSecret: process.env.GOOGLE_CLIENT_SECRET || "",
+            },
+        },
+        basePath: "/api/auth",
+        advanced: {
+            useSecureCookies: true, // Behind Caddy reverse proxy — force consistent __Secure- prefix
+        },
+        trustedOrigins: [
+            "https://browse.hanzilla.co",
+            "https://api.hanzilla.co",
+            "http://localhost:3000",
+            "http://localhost:3456",
+        ],
+        databaseHooks: {
+            user: {
+                create: {
+                    after: async (user) => {
+                        // Auto-provision workspace when a new user is created
+                        const userId = user.id;
+                        if (!userId)
+                            return;
+                        const client = await getProvisionPool().connect();
+                        try {
+                            await client.query("BEGIN");
+                            const wsRes = await client.query("INSERT INTO workspaces (name) VALUES ($1) RETURNING id", [`${user.name || "My"}'s Workspace`]);
+                            const workspaceId = wsRes.rows[0].id;
+                            await client.query("INSERT INTO workspace_members (workspace_id, user_id, role) VALUES ($1, $2, 'owner')", [workspaceId, userId]);
+                            await client.query("COMMIT");
+                            log.info("Provisioned workspace", { workspaceId }, { userId });
+                        }
+                        catch (err) {
+                            await client.query("ROLLBACK").catch(() => { });
+                            log.error("Workspace provisioning error", undefined, { error: err.message });
+                        }
+                        finally {
+                            client.release();
+                        }
+                    },
+                },
+            },
+        },
+    });
+    log.info("Better Auth initialized");
+    return authInstance;
+}
+/**
+ * Resolve a Better Auth session cookie to workspace info.
+ * Returns { userId, workspaceId } or null.
+ * Uses direct DB lookup (same reason as resolveSessionProfile).
+ */
+export async function resolveSessionToWorkspace(req) {
+    try {
+        const cookieHeader = req.headers.cookie || '';
+        const tokenMatch = cookieHeader.match(/better-auth[.\-]session_token=([^;]+)/);
+        if (!tokenMatch)
+            return null;
+        const rawValue = decodeURIComponent(tokenMatch[1]);
+        const token = rawValue.split('.')[0];
+        if (!token)
+            return null;
+        const db = getProvisionPool();
+        const sessionRes = await db.query(`SELECT "userId", "expiresAt" FROM session WHERE token = $1 LIMIT 1`, [token]);
+        if (sessionRes.rows.length === 0)
+            return null;
+        if (new Date(sessionRes.rows[0].expiresAt) < new Date())
+            return null;
+        const userId = sessionRes.rows[0].userId;
+        const requestedWs = req.headers["x-workspace-id"];
+        const query = requestedWs
+            ? "SELECT workspace_id FROM workspace_members WHERE user_id = $1 AND workspace_id = $2 LIMIT 1"
+            : "SELECT workspace_id FROM workspace_members WHERE user_id = $1 ORDER BY created_at ASC LIMIT 1";
+        const params = requestedWs ? [userId, requestedWs] : [userId];
+        const res = await db.query(query, params);
+        if (res.rows.length === 0)
+            return null;
+        return { userId, workspaceId: res.rows[0].workspace_id };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve session to full profile (user name, email, workspace name).
+ * Used by GET /v1/me for the developer console.
+ *
+ * Uses direct DB lookup instead of auth.api.getSession() because
+ * Better Auth's cookie reading fails behind Caddy reverse proxy
+ * (cookie prefix mismatch between set and read paths).
+ */
+export async function resolveSessionProfile(req) {
+    try {
+        // Extract session token from cookie (handles both __Secure- and plain prefix)
+        const cookieHeader = req.headers.cookie || '';
+        const tokenMatch = cookieHeader.match(/better-auth[.\-]session_token=([^;]+)/);
+        console.error(`[AUTH] step1: match=${!!tokenMatch} cookieLen=${cookieHeader.length}`);
+        if (!tokenMatch)
+            return null;
+        // Token format: "rawToken.signature" — we only need the raw token for DB lookup
+        const rawValue = decodeURIComponent(tokenMatch[1]);
+        const token = rawValue.split('.')[0];
+        console.error(`[AUTH] step2: token=${token.substring(0, 10)}... rawLen=${rawValue.length}`);
+        if (!token)
+            return null;
+        const db = getProvisionPool();
+        const sessionRes = await db.query(`SELECT s."userId", s."expiresAt", u.name, u.email
+       FROM session s
+       JOIN "user" u ON u.id = s."userId"
+       WHERE s.token = $1 LIMIT 1`, [token]);
+        console.error(`[AUTH] step3: rows=${sessionRes.rows.length}`);
+        if (sessionRes.rows.length === 0)
+            return null;
+        const row = sessionRes.rows[0];
+        // Check expiry
+        console.error(`[AUTH] step4: userId=${row.userId} expires=${row.expiresAt} expired=${new Date(row.expiresAt) < new Date()}`);
+        if (new Date(row.expiresAt) < new Date())
+            return null;
+        const wsRes = await db.query(`SELECT wm.workspace_id, w.name as workspace_name
+       FROM workspace_members wm
+       JOIN workspaces w ON w.id = wm.workspace_id
+       WHERE wm.user_id = $1
+       ORDER BY wm.created_at ASC LIMIT 1`, [row.userId]);
+        console.error(`[AUTH] step5: wsRows=${wsRes.rows.length}`);
+        if (wsRes.rows.length === 0)
+            return null;
+        return {
+            userId: row.userId,
+            workspaceId: wsRes.rows[0].workspace_id,
+            userName: row.name || "",
+            userEmail: row.email || "",
+            workspaceName: wsRes.rows[0].workspace_name,
+            plan: "free",
+        };
+    }
+    catch (err) {
+        log.error("resolveSessionProfile failed", undefined, { error: err.message });
+        return null;
+    }
+}

package/dist/managed/billing.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Stripe Billing Integration
+ *
+ * Wired but not yet activated in production (billing env vars not set).
+ *
+ * What's implemented:
+ * - Checkout session creation with workspace metadata
+ * - Webhook handlers persist subscription status to workspace
+ * - Usage metering called from task completion flow
+ * - Plan gating scaffolded in api.ts (soft check, log only — uncomment to enforce)
+ * - Customer ID mapped from checkout.session.completed webhook
+ *
+ * To activate:
+ * 1. Set STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_MANAGED_PRICE_ID
+ * 2. Optionally set STRIPE_API_METER_ID for usage metering
+ * 3. Uncomment the 402 return in api.ts handleCreateTask() to enforce plan gating
+ * 4. Run schema migrations (ALTER TABLE workspaces ADD COLUMN ...)
+ *
+ * Requires env vars:
+ * - STRIPE_SECRET_KEY
+ * - STRIPE_WEBHOOK_SECRET
+ * - STRIPE_MANAGED_PRICE_ID (monthly subscription price)
+ * - STRIPE_API_METER_ID (usage meter for API tasks)
+ */
+import type * as fileStore from "./store.js";
+/** Set the backing store so billing can persist webhook results. */
+export declare function setBillingStore(store: typeof fileStore): void;
+export declare function initBilling(): boolean;
+export declare function isBillingEnabled(): boolean;
+/**
+ * Create a Stripe Checkout session to buy credits.
+ */
+export declare function createCheckoutSession(params: {
+    workspaceId: string;
+    userId: string;
+    email?: string;
+    credits?: number;
+    successUrl: string;
+    cancelUrl: string;
+}): Promise<{
+    url: string;
+}>;
+/**
+ * Create a Stripe Billing Portal session for managing subscription.
+ */
+export declare function createPortalSession(params: {
+    customerId: string;
+    returnUrl: string;
+}): Promise<{
+    url: string;
+}>;
+/**
+ * Record a completed API task for usage-based billing.
+ * Uses Stripe's Billing Meter Events API.
+ */
+export declare function recordTaskUsage(params: {
+    workspaceId: string;
+    taskId: string;
+    steps: number;
+    inputTokens: number;
+    outputTokens: number;
+}): Promise<void>;
+/**
+ * Handle Stripe webhook events.
+ * Returns true if the event was handled, false if not recognized.
+ */
+export declare function handleWebhook(rawBody: string, signature: string): Promise<{
+    handled: boolean;
+    event?: string;
+}>;

package/dist/managed/billing.js

@@ -0,0 +1,227 @@
+/**
+ * Stripe Billing Integration
+ *
+ * Wired but not yet activated in production (billing env vars not set).
+ *
+ * What's implemented:
+ * - Checkout session creation with workspace metadata
+ * - Webhook handlers persist subscription status to workspace
+ * - Usage metering called from task completion flow
+ * - Plan gating scaffolded in api.ts (soft check, log only — uncomment to enforce)
+ * - Customer ID mapped from checkout.session.completed webhook
+ *
+ * To activate:
+ * 1. Set STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_MANAGED_PRICE_ID
+ * 2. Optionally set STRIPE_API_METER_ID for usage metering
+ * 3. Uncomment the 402 return in api.ts handleCreateTask() to enforce plan gating
+ * 4. Run schema migrations (ALTER TABLE workspaces ADD COLUMN ...)
+ *
+ * Requires env vars:
+ * - STRIPE_SECRET_KEY
+ * - STRIPE_WEBHOOK_SECRET
+ * - STRIPE_MANAGED_PRICE_ID (monthly subscription price)
+ * - STRIPE_API_METER_ID (usage meter for API tasks)
+ */
+import Stripe from "stripe";
+import { log } from "./log.js";
+let stripe = null;
+let S = null;
+/** Set the backing store so billing can persist webhook results. */
+export function setBillingStore(store) {
+    S = store;
+}
+export function initBilling() {
+    const key = process.env.STRIPE_SECRET_KEY;
+    if (!key) {
+        log.info("No STRIPE_SECRET_KEY — billing disabled");
+        return false;
+    }
+    stripe = new Stripe(key);
+    log.info("Stripe billing initialized");
+    return true;
+}
+export function isBillingEnabled() {
+    return stripe !== null;
+}
+// --- Credit Packs ---
+const CREDIT_PACKS = {};
+/**
+ * Initialize credit packs from env. Format: STRIPE_CREDIT_PACK_<N>=<credits>:<stripe_price_id>
+ * Example: STRIPE_CREDIT_PACK_1=100:price_abc123
+ *          STRIPE_CREDIT_PACK_2=500:price_def456
+ * Or use a single default: STRIPE_CREDIT_PRICE_ID for 100 credits.
+ */
+function loadCreditPacks() {
+    // Default pack
+    const defaultPrice = process.env.STRIPE_CREDIT_PRICE_ID;
+    if (defaultPrice) {
+        CREDIT_PACKS["100"] = { credits: 100, priceId: defaultPrice };
+    }
+    // Numbered packs
+    for (let i = 1; i <= 5; i++) {
+        const val = process.env[`STRIPE_CREDIT_PACK_${i}`];
+        if (val) {
+            const [credits, priceId] = val.split(":");
+            if (credits && priceId) {
+                CREDIT_PACKS[credits] = { credits: parseInt(credits, 10), priceId };
+            }
+        }
+    }
+}
+/**
+ * Create a Stripe Checkout session to buy credits.
+ */
+export async function createCheckoutSession(params) {
+    if (!stripe || !S)
+        throw new Error("Billing not configured");
+    loadCreditPacks();
+    const requestedCredits = String(params.credits || 100);
+    const pack = CREDIT_PACKS[requestedCredits];
+    if (!pack) {
+        const available = Object.keys(CREDIT_PACKS).join(", ");
+        throw new Error(`No credit pack for ${requestedCredits} credits. Available: ${available || "none configured"}`);
+    }
+    const workspace = await S.getWorkspace(params.workspaceId);
+    let customerId;
+    if (workspace?.stripeCustomerId) {
+        customerId = workspace.stripeCustomerId;
+    }
+    const sessionParams = {
+        mode: "payment",
+        line_items: [{ price: pack.priceId, quantity: 1 }],
+        success_url: params.successUrl,
+        cancel_url: params.cancelUrl,
+        metadata: {
+            workspace_id: params.workspaceId,
+            user_id: params.userId,
+            credits: String(pack.credits),
+        },
+    };
+    if (customerId) {
+        sessionParams.customer = customerId;
+    }
+    else {
+        sessionParams.customer_email = params.email;
+    }
+    const session = await stripe.checkout.sessions.create(sessionParams);
+    return { url: session.url };
+}
+/**
+ * Create a Stripe Billing Portal session for managing subscription.
+ */
+export async function createPortalSession(params) {
+    if (!stripe)
+        throw new Error("Billing not configured");
+    const session = await stripe.billingPortal.sessions.create({
+        customer: params.customerId,
+        return_url: params.returnUrl,
+    });
+    return { url: session.url };
+}
+// --- Usage Metering ---
+/**
+ * Record a completed API task for usage-based billing.
+ * Uses Stripe's Billing Meter Events API.
+ */
+export async function recordTaskUsage(params) {
+    if (!stripe || !S)
+        return;
+    const meterId = process.env.STRIPE_API_METER_ID;
+    if (!meterId)
+        return;
+    // Look up the workspace's Stripe customer ID
+    const workspace = await S.getWorkspace(params.workspaceId);
+    if (!workspace?.stripeCustomerId) {
+        log.warn("Cannot meter usage — workspace has no Stripe customer ID", { workspaceId: params.workspaceId, taskId: params.taskId });
+        return;
+    }
+    try {
+        await stripe.billing.meterEvents.create({
+            event_name: "browser_task_completed",
+            payload: {
+                stripe_customer_id: workspace.stripeCustomerId,
+                value: "1",
+            },
+        });
+    }
+    catch (err) {
+        log.error("Failed to record usage", { taskId: params.taskId }, { error: err.message });
+    }
+}
+// --- Webhooks ---
+/**
+ * Handle Stripe webhook events.
+ * Returns true if the event was handled, false if not recognized.
+ */
+export async function handleWebhook(rawBody, signature) {
+    if (!stripe)
+        return { handled: false };
+    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+    if (!webhookSecret)
+        return { handled: false };
+    let event;
+    try {
+        event = stripe.webhooks.constructEvent(rawBody, signature, webhookSecret);
+    }
+    catch (err) {
+        log.error("Webhook signature verification failed", undefined, { error: err.message });
+        return { handled: false };
+    }
+    switch (event.type) {
+        case "checkout.session.completed": {
+            const session = event.data.object;
+            const workspaceId = session.metadata?.workspace_id;
+            const credits = parseInt(session.metadata?.credits || "0", 10);
+            if (workspaceId && S) {
+                try {
+                    // Persist Stripe customer ID
+                    await S.updateWorkspaceBilling(workspaceId, {
+                        stripeCustomerId: session.customer,
+                    });
+                    // Add purchased credits
+                    if (credits > 0) {
+                        const newBalance = await S.addCredits(workspaceId, credits);
+                        log.info("Credits purchased", { workspaceId }, { credits, newBalance });
+                    }
+                }
+                catch (err) {
+                    log.error("Failed to persist checkout result", { workspaceId }, { error: err.message });
+                }
+            }
+            return { handled: true, event: event.type };
+        }
+        case "customer.subscription.updated":
+        case "customer.subscription.deleted": {
+            const subscription = event.data.object;
+            const workspaceId = subscription.metadata?.workspace_id;
+            const status = subscription.status;
+            if (workspaceId && S) {
+                const plan = status === "active" ? "pro" : "free";
+                const subStatus = status === "active" ? "active"
+                    : status === "canceled" ? "cancelled"
+                        : status === "past_due" ? "past_due"
+                            : "cancelled";
+                try {
+                    await S.updateWorkspaceBilling(workspaceId, {
+                        plan,
+                        subscriptionStatus: subStatus,
+                    });
+                    log.info("Subscription updated", { workspaceId }, { event: event.type, plan, status: subStatus });
+                }
+                catch (err) {
+                    log.error("Failed to persist subscription update", { workspaceId }, { error: err.message });
+                }
+            }
+            return { handled: true, event: event.type };
+        }
+        case "invoice.payment_failed": {
+            const invoice = event.data.object;
+            // Find workspace by Stripe customer ID — requires iterating or a reverse lookup.
+            // For now, log the failure. The subscription.updated webhook will handle the status change.
+            log.warn("Payment failed", undefined, { customer: String(invoice.customer) });
+            return { handled: true, event: event.type };
+        }
+        default:
+            return { handled: false, event: event.type };
+    }
+}