@taskforcehq/taskforce 0.3.170 → 0.3.300

package/dist/server/routes/billing.js

@@ -0,0 +1,2001 @@
+import Stripe from 'stripe';
+import { parseJsonBody } from '../routes.js';
+import { resolveTaskforceCloudEnvironmentFromHostname } from '../../config/cloudEnvironment.js';
+import { buildMockStripeHostedCheckoutUrl, completeMockStripeCheckoutSession, createMockStripeClient, isMockStripeClient, isMockStripeEnabled, readMockStripeCheckoutSession, renderMockStripeCheckoutHtml } from '../mockStripe.js';
+const BILLING_CONFIG_KEY_PLAN = 'billing.config.v1';
+const PRICE_METADATA_PLAN_VERSION = 'taskforce_plan_version_id';
+const BILLING_DIAGNOSTIC_RETENTION_DAYS = 30;
+const BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES = 8 * 1024;
+const TASKFORCE_PROXY_ORIGIN_HOST_HEADER = 'x-taskforce-origin-host';
+const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = 'x-taskforce-origin-proto';
+const TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER = 'x-taskforce-origin-base-url';
+const TASKFORCE_PROXY_ORIGIN_RUNTIME_HEADER = 'x-taskforce-origin-runtime';
+function parsePricingType(raw) {
+    const value = String(raw || '').trim().toLowerCase();
+    if (value === 'stripe' || value === 'free')
+        return value;
+    return null;
+}
+function buildFreePricingSyntheticId(planVersionId, interval) {
+    return `free:${planVersionId}:${interval}`;
+}
+function isoFromUnixSeconds(raw) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    return new Date(Math.floor(value) * 1000).toISOString();
+}
+function parseInterval(raw) {
+    const value = String(raw || '').trim().toLowerCase();
+    if (value === 'month' || value === 'year')
+        return value;
+    return null;
+}
+function normalizeEmail(raw) {
+    return String(raw || '').trim().toLowerCase();
+}
+function parseRequestUrl(req) {
+    return new URL(req.url || '/', 'https://taskforce.local');
+}
+async function listStripePriceOptions(intervalFilter) {
+    const stripe = getStripeClient();
+    const options = [];
+    let startingAfter;
+    while (true) {
+        const page = await stripe.prices.list({
+            active: true,
+            type: 'recurring',
+            limit: 100,
+            starting_after: startingAfter,
+            expand: ['data.product']
+        });
+        for (const price of page.data) {
+            const interval = parseInterval(price.recurring?.interval || '');
+            if (!interval)
+                continue;
+            if (intervalFilter && interval !== intervalFilter)
+                continue;
+            const product = typeof price.product === 'string' ? null : price.product;
+            options.push({
+                stripePriceId: price.id,
+                interval,
+                unitAmount: typeof price.unit_amount === 'number' ? price.unit_amount : null,
+                currency: price.currency ? String(price.currency) : null,
+                active: price.active === true,
+                nickname: price.nickname ? String(price.nickname) : null,
+                productId: typeof price.product === 'string' ? price.product : (product?.id ? String(product.id) : null),
+                productName: product?.deleted ? null : (product?.name ? String(product.name) : null)
+            });
+        }
+        if (!page.has_more || page.data.length === 0)
+            break;
+        startingAfter = page.data[page.data.length - 1]?.id;
+        if (!startingAfter)
+            break;
+    }
+    return options.sort((a, b) => {
+        if (a.interval !== b.interval)
+            return a.interval.localeCompare(b.interval);
+        return a.stripePriceId.localeCompare(b.stripePriceId);
+    });
+}
+function resolveSubscriptionCurrentPeriodEnd(subscription) {
+    const itemPeriods = Array.isArray(subscription.items?.data)
+        ? subscription.items.data
+            .map((item) => isoFromUnixSeconds(item?.current_period_end))
+            .filter((value) => Boolean(value))
+        : [];
+    if (itemPeriods.length === 0)
+        return null;
+    return itemPeriods.sort()[itemPeriods.length - 1] || null;
+}
+function resolveInvoiceSubscriptionId(invoice) {
+    const parentSubscription = String(invoice?.parent?.subscription_details?.subscription || '').trim();
+    if (parentSubscription)
+        return parentSubscription;
+    const lineSubscription = String(invoice.lines?.data?.[0]?.subscription || '').trim();
+    return lineSubscription;
+}
+function requestRuntimeMode(req) {
+    const value = String(req.headers['x-taskforce-runtime-mode'] || '').trim().toLowerCase();
+    return value === 'cloud' ? 'cloud' : 'local';
+}
+function requestPricingEnvironment(req) {
+    const hostCandidates = [
+        String(req.headers.host || '').trim(),
+        String(req.headers['x-forwarded-host'] || '').trim()
+    ];
+    for (const rawHost of hostCandidates) {
+        const hostname = rawHost.split(',')[0].trim().replace(/:\d+$/, '');
+        const environment = resolveTaskforceCloudEnvironmentFromHostname(hostname);
+        if (environment)
+            return environment;
+    }
+    return 'production';
+}
+function parseBoolean(value, fallback = false) {
+    const normalized = String(value ?? '').trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on')
+        return true;
+    if (normalized === 'false' || normalized === '0' || normalized === 'no' || normalized === 'off')
+        return false;
+    return fallback;
+}
+function parsePositiveIntBounded(raw, fallback, min, max) {
+    const parsed = Number.parseInt(String(raw || '').trim(), 10);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(min, Math.min(max, parsed));
+}
+function readHeaderFirstValue(raw) {
+    return String(raw || '').split(',').map((value) => value.trim()).find(Boolean) || '';
+}
+function normalizeOriginHost(raw) {
+    return readHeaderFirstValue(raw).replace(/\/+$/, '');
+}
+function normalizeOriginProto(raw, fallback = 'https') {
+    return readHeaderFirstValue(raw).toLowerCase() === 'http' ? 'http' : fallback;
+}
+function resolveRequestProto(req, raw, fallback = 'https') {
+    const normalized = readHeaderFirstValue(raw).toLowerCase();
+    if (normalized === 'http')
+        return 'http';
+    if (normalized === 'https')
+        return 'https';
+    return req.socket?.encrypted ? 'https' : fallback;
+}
+function isLocalDevelopmentHost(raw) {
+    const host = normalizeOriginHost(raw).replace(/:\d+$/, '').toLowerCase();
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+function resolveRequestOrigin(req) {
+    const explicitBaseUrl = readHeaderFirstValue(req.headers[TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER]);
+    const explicitHost = normalizeOriginHost(req.headers[TASKFORCE_PROXY_ORIGIN_HOST_HEADER]);
+    const explicitProto = resolveRequestProto(req, req.headers[TASKFORCE_PROXY_ORIGIN_PROTO_HEADER], 'http');
+    const originRuntime = readHeaderFirstValue(req.headers[TASKFORCE_PROXY_ORIGIN_RUNTIME_HEADER]).toLowerCase();
+    if (explicitBaseUrl) {
+        try {
+            const parsed = new URL(explicitBaseUrl);
+            const proto = parsed.protocol === 'http:' ? 'http' : 'https';
+            return {
+                baseUrl: `${proto}://${parsed.host.replace(/\/+$/, '')}`,
+                host: parsed.host.replace(/\/+$/, ''),
+                proto,
+                source: 'explicit-proxy-origin',
+                localProxyRequest: originRuntime === 'local-proxy' || isLocalDevelopmentHost(parsed.host)
+            };
+        }
+        catch {
+            // Fall through to explicit host/proto parsing.
+        }
+    }
+    if (explicitHost) {
+        return {
+            baseUrl: `${explicitProto}://${explicitHost}`,
+            host: explicitHost,
+            proto: explicitProto,
+            source: 'explicit-proxy-origin',
+            localProxyRequest: originRuntime === 'local-proxy' || isLocalDevelopmentHost(explicitHost)
+        };
+    }
+    const forwardedHost = normalizeOriginHost(req.headers['x-forwarded-host']);
+    const forwardedProto = resolveRequestProto(req, req.headers['x-forwarded-proto'], 'http');
+    if (forwardedHost) {
+        return {
+            baseUrl: `${forwardedProto}://${forwardedHost}`,
+            host: forwardedHost,
+            proto: forwardedProto,
+            source: 'forwarded',
+            localProxyRequest: isLocalDevelopmentHost(forwardedHost)
+        };
+    }
+    const requestHost = normalizeOriginHost(req.headers.host || 'localhost');
+    const requestProto = resolveRequestProto(req, req.headers['x-forwarded-proto'], 'http');
+    return {
+        baseUrl: `${requestProto}://${requestHost}`,
+        host: requestHost,
+        proto: requestProto,
+        source: 'request-host',
+        localProxyRequest: isLocalDevelopmentHost(requestHost)
+    };
+}
+function resolveBaseUrl(req) {
+    const origin = resolveRequestOrigin(req);
+    if (origin.localProxyRequest && !isLocalDevelopmentHost(origin.host)) {
+        throw new Error(`Billing return URL origin mismatch: expected local development host but resolved ${origin.baseUrl}`);
+    }
+    return origin.baseUrl;
+}
+async function readRawBody(req, maxBytes = 1_048_576) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes) {
+            const error = new Error(`Payload too large (max ${maxBytes} bytes)`);
+            error.statusCode = 413;
+            throw error;
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
+function mapStripeStatusToCanonicalState(statusRaw) {
+    const status = String(statusRaw || '').trim().toLowerCase();
+    if (status === 'trialing')
+        return 'trialing';
+    if (status === 'active')
+        return 'active';
+    if (status === 'past_due')
+        return 'grace';
+    return 'canceled';
+}
+function isMissingStripeCustomerError(error) {
+    const code = String(error?.code || '').trim().toLowerCase();
+    const message = String(error?.message || '').trim().toLowerCase();
+    return code === 'resource_missing' && message.includes('customer');
+}
+function redactStripePayload(input) {
+    const blockedKeys = new Set([
+        'billing_details',
+        'customer_details',
+        'payment_method',
+        'payment_method_details',
+        'payment_intent',
+        'charges',
+        'source',
+        'sources',
+        'card',
+        'default_source'
+    ]);
+    const visit = (value, depth) => {
+        if (depth > 6)
+            return '[truncated-depth]';
+        if (value === null || value === undefined)
+            return value;
+        if (Array.isArray(value))
+            return value.slice(0, 30).map((item) => visit(item, depth + 1));
+        if (typeof value !== 'object')
+            return value;
+        const source = value;
+        const out = {};
+        for (const [key, child] of Object.entries(source)) {
+            if (blockedKeys.has(key))
+                continue;
+            out[key] = visit(child, depth + 1);
+        }
+        return out;
+    };
+    const redacted = visit(input, 0);
+    return redacted && typeof redacted === 'object' && !Array.isArray(redacted)
+        ? redacted
+        : {};
+}
+function boundedPayloadExcerpt(payload) {
+    const raw = JSON.stringify(payload);
+    if (Buffer.byteLength(raw, 'utf8') <= BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES)
+        return raw;
+    const truncated = raw.slice(0, BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES);
+    return `${truncated}...[truncated]`;
+}
+function parseBillingConfig(raw) {
+    const fallback = {
+        tiers: {},
+        taxEnabled: false,
+        billingAddress: 'auto'
+    };
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return fallback;
+    const record = raw;
+    const billingAddress = String(record.billing_address || '').trim().toLowerCase() === 'required'
+        ? 'required'
+        : 'auto';
+    return {
+        tiers: record.tiers && typeof record.tiers === 'object' && !Array.isArray(record.tiers)
+            ? record.tiers
+            : {},
+        taxEnabled: parseBoolean(record.tax_enabled, false),
+        billingAddress
+    };
+}
+function billingDisabledResponse(res) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Billing is disabled.' }));
+}
+function cloudOnlyResponse(res) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Billing is only available in cloud runtime.' }));
+}
+function localPricingProxyRequiredResponse(res) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Pricing must be served through the configured cloud pricing proxy in local runtime.' }));
+}
+function getStripeClient() {
+    const key = String(process.env.TASKFORCE_STRIPE_SECRET_KEY || '').trim();
+    if (!key) {
+        const error = new Error('TASKFORCE_STRIPE_SECRET_KEY is not configured.');
+        error.statusCode = 500;
+        throw error;
+    }
+    if (isMockStripeEnabled(key)) {
+        return createMockStripeClient();
+    }
+    return new Stripe(key);
+}
+function resolveHostedServerBaseUrl(req) {
+    const host = normalizeOriginHost(req.headers.host || '127.0.0.1');
+    const proto = normalizeOriginProto(req.headers['x-forwarded-proto'], 'http');
+    return `${proto}://${host}`;
+}
+function readBillingConfig(core) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT payload
+        FROM system_settings
+        WHERE tenant_id = ? AND settings_key = ?
+        LIMIT 1
+    `).get(tenantId, BILLING_CONFIG_KEY_PLAN);
+    if (!row?.payload)
+        return parseBillingConfig({});
+    try {
+        return parseBillingConfig(JSON.parse(row.payload));
+    }
+    catch {
+        return parseBillingConfig({});
+    }
+}
+function writeBillingConfig(core, payload) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    db.prepare(`
+        INSERT INTO system_settings (tenant_id, settings_key, payload, updated_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (tenant_id, settings_key) DO UPDATE SET
+            payload = excluded.payload,
+            updated_at = excluded.updated_at
+    `).run(tenantId, BILLING_CONFIG_KEY_PLAN, JSON.stringify({
+        tiers: payload.tiers,
+        tax_enabled: payload.taxEnabled,
+        billing_address: payload.billingAddress
+    }), now);
+}
+function resolveStripePriceIdForPlanVersion(core, planVersionIdRaw, intervalRaw) {
+    const planVersionId = String(planVersionIdRaw || '').trim();
+    const interval = parseInterval(intervalRaw);
+    if (!planVersionId || !interval)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT stripe_price_id
+        FROM billing_price_mappings
+        WHERE tenant_id = ?
+          AND plan_version_id = ?
+          AND billing_interval = ?
+          AND active = 1
+          AND COALESCE(pricing_type, 'stripe') = 'stripe'
+        LIMIT 1
+    `).get(tenantId, planVersionId, interval);
+    return row?.stripe_price_id ? String(row.stripe_price_id) : null;
+}
+function resolveActivePricingForPlanVersion(core, planVersionIdRaw, intervalRaw) {
+    const planVersionId = String(planVersionIdRaw || '').trim();
+    const interval = parseInterval(intervalRaw);
+    if (!planVersionId || !interval)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT stripe_price_id, pricing_type
+        FROM billing_price_mappings
+        WHERE tenant_id = ?
+          AND plan_version_id = ?
+          AND billing_interval = ?
+          AND active = 1
+        LIMIT 1
+    `).get(tenantId, planVersionId, interval);
+    if (!row)
+        return null;
+    const pricingType = parsePricingType(row.pricing_type) || 'stripe';
+    return {
+        pricingType,
+        stripePriceId: pricingType === 'stripe' && row.stripe_price_id ? String(row.stripe_price_id) : null
+    };
+}
+function resolvePlanVersionIdForPriceIdFallback(core, priceIdRaw) {
+    const priceId = String(priceIdRaw || '').trim();
+    if (!priceId)
+        return { planVersionId: null, reason: 'missing' };
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const rows = db.prepare(`
+        SELECT DISTINCT plan_version_id
+        FROM billing_price_mappings
+        WHERE tenant_id = ?
+          AND stripe_price_id = ?
+          AND active = 1
+        ORDER BY plan_version_id ASC
+    `).all(tenantId, priceId);
+    if (rows.length === 0)
+        return { planVersionId: null, reason: 'missing' };
+    if (rows.length > 1)
+        return { planVersionId: null, reason: 'ambiguous' };
+    return {
+        planVersionId: rows[0]?.plan_version_id ? String(rows[0].plan_version_id) : null,
+        reason: null
+    };
+}
+function resolvePlanVersionIdForBillingEvent(core, candidatePlanVersionIds, fallbackPriceId) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    for (const candidate of candidatePlanVersionIds) {
+        const planVersionId = String(candidate || '').trim();
+        if (!planVersionId)
+            continue;
+        const row = db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_version_id = ?
+            LIMIT 1
+        `).get(tenantId, planVersionId);
+        if (row?.plan_version_id) {
+            return { planVersionId: String(row.plan_version_id), source: 'metadata', reason: null };
+        }
+    }
+    const fallback = resolvePlanVersionIdForPriceIdFallback(core, fallbackPriceId);
+    return {
+        planVersionId: fallback.planVersionId,
+        source: fallback.planVersionId ? 'price' : null,
+        reason: fallback.reason
+    };
+}
+function resolvePlanIdForVersion(core, planVersionIdRaw) {
+    const planVersionId = String(planVersionIdRaw || '').trim();
+    if (!planVersionId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT plan_id
+        FROM plan_versions
+        WHERE tenant_id = ? AND plan_version_id = ?
+        LIMIT 1
+    `).get(tenantId, planVersionId);
+    return row?.plan_id ? String(row.plan_id) : null;
+}
+function getEntitlementRow(core, userIdRaw) {
+    const userId = String(userIdRaw || '').trim();
+    if (!userId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT account_id, plan_version_id, entitlement_state
+        FROM account_entitlements
+        WHERE tenant_id = ? AND account_id = ?
+        LIMIT 1
+    `).get(tenantId, userId);
+    return row || null;
+}
+function upsertCanonicalEntitlement(core, input) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    db.prepare(`
+        INSERT INTO account_entitlements (account_id, tenant_id, plan_version_id, entitlement_state, effective_at, effective_until, updated_by, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (account_id) DO UPDATE SET
+            plan_version_id = excluded.plan_version_id,
+            entitlement_state = excluded.entitlement_state,
+            effective_at = excluded.effective_at,
+            effective_until = excluded.effective_until,
+            updated_by = excluded.updated_by,
+            updated_at = excluded.updated_at
+    `).run(input.userId, tenantId, input.planVersionId, input.state, input.effectiveAt || now, input.effectiveUntil || null, input.updatedBy || 'stripe-webhook', now, now);
+}
+function upsertBillingMirror(core, input) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    const existingRow = db.prepare(`
+        SELECT tier, entitlement_state
+        FROM user_billing
+        WHERE tenant_id = ? AND user_id = ?
+        LIMIT 1
+    `).get(tenantId, input.userId);
+    const resolvedPlanId = String(input.planId || existingRow?.tier || '').trim() || '';
+    const resolvedCanonicalState = String(input.canonicalState || existingRow?.entitlement_state || 'active').trim() || 'active';
+    db.prepare(`
+        INSERT INTO user_billing (
+            user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval,
+            entitlement_state, trial_end, current_period_end, effective_until, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (user_id) DO UPDATE SET
+            stripe_customer_id = COALESCE(excluded.stripe_customer_id, user_billing.stripe_customer_id),
+            stripe_subscription_id = COALESCE(excluded.stripe_subscription_id, user_billing.stripe_subscription_id),
+            stripe_price_id = COALESCE(excluded.stripe_price_id, user_billing.stripe_price_id),
+            stripe_status = COALESCE(excluded.stripe_status, user_billing.stripe_status),
+            tier = COALESCE(excluded.tier, user_billing.tier),
+            billing_interval = COALESCE(excluded.billing_interval, user_billing.billing_interval),
+            entitlement_state = COALESCE(excluded.entitlement_state, user_billing.entitlement_state),
+            trial_end = COALESCE(excluded.trial_end, user_billing.trial_end),
+            current_period_end = COALESCE(excluded.current_period_end, user_billing.current_period_end),
+            effective_until = COALESCE(excluded.effective_until, user_billing.effective_until),
+            updated_at = excluded.updated_at
+    `).run(input.userId, tenantId, input.stripeCustomerId || null, input.stripeSubscriptionId || null, input.stripePriceId || null, input.stripeStatus || null, resolvedPlanId, input.billingInterval || null, resolvedCanonicalState, input.trialEnd || null, input.currentPeriodEnd || null, input.effectiveUntil || null, now, now);
+}
+function applySubscriptionSnapshot(core, input) {
+    const { userId, subscription, source } = input;
+    const customerId = String(subscription.customer || '').trim();
+    const stripeStatus = String(subscription.status || '').trim().toLowerCase();
+    const priceId = String(subscription.items?.data?.[0]?.price?.id || '').trim();
+    const billingInterval = parseInterval(subscription.items?.data?.[0]?.price?.recurring?.interval || '');
+    const planVersionResolution = resolvePlanVersionIdForBillingEvent(core, [
+        subscription.metadata?.planVersionId,
+        subscription.metadata?.plan_version_id
+    ], priceId);
+    const planVersionId = planVersionResolution.planVersionId;
+    const existingEntitlement = getEntitlementRow(core, userId);
+    const nowIso = new Date().toISOString();
+    const currentPeriodEnd = resolveSubscriptionCurrentPeriodEnd(subscription);
+    const trialEnd = isoFromUnixSeconds(subscription.trial_end);
+    const canceledState = stripeStatus === 'canceled'
+        ? (currentPeriodEnd && currentPeriodEnd > nowIso ? 'active' : 'canceled')
+        : null;
+    const canonicalState = canceledState || mapStripeStatusToCanonicalState(stripeStatus);
+    const effectiveUntil = stripeStatus === 'canceled'
+        ? currentPeriodEnd
+        : (currentPeriodEnd || null);
+    upsertBillingMirror(core, {
+        userId,
+        stripeCustomerId: customerId || null,
+        stripeSubscriptionId: String(subscription.id || '').trim() || null,
+        stripePriceId: priceId || null,
+        stripeStatus: stripeStatus || null,
+        planId: planVersionId ? resolvePlanIdForVersion(core, planVersionId) : null,
+        billingInterval: billingInterval || null,
+        canonicalState,
+        trialEnd,
+        currentPeriodEnd,
+        effectiveUntil
+    });
+    if (planVersionId) {
+        upsertCanonicalEntitlement(core, {
+            userId,
+            planVersionId: planVersionId || existingEntitlement?.plan_version_id || core.getDefaultPlanVersionIdByMode('personal', { allowFallback: true }),
+            state: canonicalState,
+            effectiveAt: trialEnd || nowIso,
+            effectiveUntil,
+            updatedBy: source
+        });
+    }
+    return { planVersionId, canonicalState };
+}
+async function reconcileBillingFromStripe(core, userIdRaw, subscriptionIdRaw) {
+    const userId = String(userIdRaw || '').trim();
+    const subscriptionId = String(subscriptionIdRaw || '').trim();
+    if (!userId || !subscriptionId)
+        return false;
+    const stripe = getStripeClient();
+    const subscription = await stripe.subscriptions.retrieve(subscriptionId);
+    applySubscriptionSnapshot(core, {
+        userId,
+        subscription,
+        source: 'checkout-confirm'
+    });
+    return true;
+}
+function resolveUserIdByCustomer(core, customerIdRaw) {
+    const customerId = String(customerIdRaw || '').trim();
+    if (!customerId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT user_id
+        FROM user_billing
+        WHERE tenant_id = ? AND stripe_customer_id = ?
+        LIMIT 1
+    `).get(tenantId, customerId);
+    return row?.user_id ? String(row.user_id) : null;
+}
+function resolveUserIdBySubscription(core, subscriptionIdRaw) {
+    const subscriptionId = String(subscriptionIdRaw || '').trim();
+    if (!subscriptionId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT user_id
+        FROM user_billing
+        WHERE tenant_id = ? AND stripe_subscription_id = ?
+        LIMIT 1
+    `).get(tenantId, subscriptionId);
+    return row?.user_id ? String(row.user_id) : null;
+}
+function getBillingMirrorRow(core, userIdRaw) {
+    const userId = String(userIdRaw || '').trim();
+    if (!userId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    return db.prepare(`
+        SELECT stripe_status, stripe_customer_id, stripe_subscription_id, stripe_price_id, billing_interval, trial_end, current_period_end, effective_until, entitlement_state, tier
+        FROM user_billing
+        WHERE tenant_id = ? AND user_id = ?
+        LIMIT 1
+    `).get(tenantId, userId);
+}
+function isStripeManagedSubscriptionStatus(statusRaw) {
+    const status = String(statusRaw || '').trim().toLowerCase();
+    return status === 'trialing'
+        || status === 'active'
+        || status === 'past_due'
+        || status === 'unpaid'
+        || status === 'paused';
+}
+async function discoverStripeAccountStateForUser(core, input) {
+    const stripe = getStripeClient();
+    const customerIds = [];
+    const seenCustomerIds = new Set();
+    const pushCustomerId = (raw) => {
+        const customerId = String(raw || '').trim();
+        if (!customerId || seenCustomerIds.has(customerId))
+            return;
+        seenCustomerIds.add(customerId);
+        customerIds.push(customerId);
+    };
+    pushCustomerId(input.currentCustomerId);
+    const normalizedEmail = normalizeEmail(input.normalizedEmail);
+    if (normalizedEmail && stripe.customers?.list) {
+        const customers = await stripe.customers.list({
+            email: normalizedEmail,
+            limit: 20
+        });
+        if (Array.isArray(customers?.data)) {
+            for (const customer of customers.data) {
+                pushCustomerId(customer?.id);
+            }
+        }
+    }
+    const activeSubscriptions = [];
+    const seenSubscriptionIds = new Set();
+    for (const customerId of customerIds) {
+        const subscriptions = await stripe.subscriptions.list({
+            customer: customerId,
+            status: 'all',
+            limit: 10
+        });
+        if (!Array.isArray(subscriptions?.data))
+            continue;
+        for (const subscription of subscriptions.data) {
+            if (!isStripeManagedSubscriptionStatus(subscription?.status))
+                continue;
+            const subscriptionId = String(subscription?.id || '').trim();
+            if (!subscriptionId || seenSubscriptionIds.has(subscriptionId))
+                continue;
+            seenSubscriptionIds.add(subscriptionId);
+            const metadataUserId = String(subscription?.metadata?.userId || subscription?.metadata?.user_id || '').trim();
+            activeSubscriptions.push({
+                customerId,
+                subscription,
+                metadataUserMatch: Boolean(metadataUserId) && metadataUserId === input.userId
+            });
+        }
+    }
+    activeSubscriptions.sort((left, right) => {
+        if (left.metadataUserMatch !== right.metadataUserMatch)
+            return left.metadataUserMatch ? -1 : 1;
+        if (left.customerId === input.currentCustomerId && right.customerId !== input.currentCustomerId)
+            return -1;
+        if (right.customerId === input.currentCustomerId && left.customerId !== input.currentCustomerId)
+            return 1;
+        return String(left.subscription.id || '').localeCompare(String(right.subscription.id || ''));
+    });
+    return {
+        preferredCustomerId: String(input.currentCustomerId || '').trim()
+            || customerIds[0]
+            || activeSubscriptions[0]?.customerId
+            || null,
+        activeSubscriptions
+    };
+}
+async function reconcileBillingMirrorIfNeeded(core, userIdRaw) {
+    const userId = String(userIdRaw || '').trim();
+    if (!userId)
+        return { row: null, conflictCode: null };
+    let row = getBillingMirrorRow(core, userId);
+    if (String(row?.stripe_subscription_id || '').trim()) {
+        try {
+            await reconcileBillingFromStripe(core, userId, row?.stripe_subscription_id);
+            row = getBillingMirrorRow(core, userId);
+        }
+        catch {
+            // Fall back to stored billing state when Stripe refresh is unavailable.
+        }
+    }
+    const userIdentity = core.resolveUserIdentity(userId);
+    const discovery = await discoverStripeAccountStateForUser(core, {
+        userId,
+        normalizedEmail: userIdentity?.email,
+        currentCustomerId: row?.stripe_customer_id || null
+    });
+    if (discovery.activeSubscriptions.length > 1) {
+        return { row, conflictCode: 'BILLING_DUPLICATE_ACTIVE_SUBSCRIPTIONS' };
+    }
+    if (discovery.activeSubscriptions.length === 1) {
+        const active = discovery.activeSubscriptions[0];
+        const discoveredSubscriptionId = String(active.subscription?.id || '').trim();
+        const discoveredCustomerId = String(active.customerId || '').trim();
+        const currentSubscriptionId = String(row?.stripe_subscription_id || '').trim();
+        const currentCustomerId = String(row?.stripe_customer_id || '').trim();
+        if (!currentCustomerId || currentCustomerId !== discoveredCustomerId || !currentSubscriptionId || currentSubscriptionId !== discoveredSubscriptionId) {
+            upsertBillingMirror(core, {
+                userId,
+                stripeCustomerId: discoveredCustomerId || null,
+                stripeSubscriptionId: discoveredSubscriptionId || null
+            });
+        }
+        applySubscriptionSnapshot(core, {
+            userId,
+            subscription: active.subscription,
+            source: 'checkout-confirm'
+        });
+        row = getBillingMirrorRow(core, userId);
+        return { row, conflictCode: null };
+    }
+    if (!String(row?.stripe_customer_id || '').trim() && discovery.preferredCustomerId) {
+        upsertBillingMirror(core, {
+            userId,
+            stripeCustomerId: discovery.preferredCustomerId
+        });
+        row = getBillingMirrorRow(core, userId);
+    }
+    return { row, conflictCode: null };
+}
+function purgeExpiredWebhookFailures(core) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const result = db.prepare(`
+        DELETE FROM stripe_webhook_failures
+        WHERE tenant_id = ?
+          AND purge_after < ?
+    `).run(tenantId, new Date().toISOString());
+    return Number(result?.changes || 0);
+}
+function recordWebhookFailure(core, input) {
+    try {
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const now = new Date();
+        const purgeAfter = new Date(now.getTime() + BILLING_DIAGNOSTIC_RETENTION_DAYS * 24 * 60 * 60 * 1000).toISOString();
+        const redacted = redactStripePayload(input.payload);
+        const excerpt = boundedPayloadExcerpt(redacted);
+        const id = `whf-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+        db.prepare(`
+            INSERT INTO stripe_webhook_failures (id, tenant_id, event_id, event_type, reason, payload_excerpt, purge_after, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(id, tenantId, input.eventId, input.eventType, input.reason, excerpt, purgeAfter, now.toISOString());
+    }
+    catch {
+        // diagnostics are best-effort only
+    }
+}
+function resolvePriceAndIntervalFromInvoice(invoice) {
+    const line = invoice.lines?.data?.find((entry) => !!entry?.price?.id || !!entry?.pricing?.price_details?.price);
+    const legacyPriceId = String(line?.price?.id || '').trim();
+    const modernPriceId = String(line?.pricing?.price_details?.price || '').trim();
+    const priceId = modernPriceId || legacyPriceId || null;
+    const recurringInterval = parseInterval(line?.price?.recurring?.interval || '');
+    return { priceId, interval: recurringInterval };
+}
+function lockWebhookEvent(core, event) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const result = db.prepare(`
+        INSERT INTO stripe_webhook_events (event_id, tenant_id, event_type, processed_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (event_id) DO NOTHING
+    `).run(event.id, tenantId, event.type, new Date().toISOString());
+    return Number(result?.changes || 0) > 0;
+}
+async function importStripePrices(core) {
+    const stripe = getStripeClient();
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    const validPlanVersionIds = new Set(db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ?
+        `).all(tenantId).map((row) => String(row.plan_version_id || '')).filter(Boolean));
+    const importedPriceIds = new Set();
+    const activeStripePriceIds = new Set();
+    const summary = {
+        imported: 0,
+        skipped: 0,
+        deactivated: 0,
+        details: []
+    };
+    let startingAfter;
+    while (true) {
+        const page = await stripe.prices.list({
+            active: true,
+            limit: 100,
+            starting_after: startingAfter,
+            type: 'recurring'
+        });
+        for (const price of page.data) {
+            activeStripePriceIds.add(String(price.id || '').trim());
+            const interval = parseInterval(price.recurring?.interval || '');
+            const planVersionId = String(price.metadata?.[PRICE_METADATA_PLAN_VERSION] || '').trim();
+            if (!interval || !planVersionId || !validPlanVersionIds.has(planVersionId)) {
+                summary.skipped += 1;
+                summary.details.push({
+                    priceId: price.id,
+                    status: 'skipped',
+                    reason: !planVersionId
+                        ? `Missing metadata ${PRICE_METADATA_PLAN_VERSION}`
+                        : (!interval ? 'Unsupported interval' : 'Unknown plan_version_id')
+                });
+                continue;
+            }
+            db.prepare(`
+                INSERT INTO billing_price_mappings (
+                    tenant_id, plan_version_id, billing_interval, stripe_price_id, active, unit_amount, currency, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, 1, ?, ?, ?, ?)
+                ON CONFLICT (tenant_id, plan_version_id, billing_interval, stripe_price_id) DO UPDATE SET
+                    active = 1,
+                    unit_amount = excluded.unit_amount,
+                    currency = excluded.currency,
+                    updated_at = excluded.updated_at
+            `).run(tenantId, planVersionId, interval, price.id, price.unit_amount, price.currency, now, now);
+            importedPriceIds.add(price.id);
+            summary.imported += 1;
+            summary.details.push({ priceId: price.id, status: 'imported' });
+        }
+        if (!page.has_more || page.data.length === 0)
+            break;
+        startingAfter = page.data[page.data.length - 1]?.id;
+        if (!startingAfter)
+            break;
+    }
+    const existing = db.prepare(`
+        SELECT stripe_price_id, pricing_type
+        FROM billing_price_mappings
+        WHERE tenant_id = ? AND active = 1
+    `).all(tenantId);
+    for (const row of existing) {
+        const priceId = String(row.stripe_price_id || '').trim();
+        const pricingType = String(row.pricing_type || '').trim().toLowerCase();
+        if (!priceId)
+            continue;
+        if (pricingType === 'free')
+            continue;
+        if (importedPriceIds.has(priceId))
+            continue;
+        if (activeStripePriceIds.has(priceId))
+            continue;
+        db.prepare(`
+            UPDATE billing_price_mappings
+            SET active = 0, updated_at = ?
+            WHERE tenant_id = ? AND stripe_price_id = ?
+        `).run(now, tenantId, priceId);
+        summary.deactivated += 1;
+    }
+    return summary;
+}
+export function registerBillingRoutes(deps) {
+    const { addRoute, core, context, ensureAuthenticatedUser, ensureAdminRole, requestUserId, resolveErrorStatusCode, auditAdminAction } = deps;
+    const billingEnabled = () => parseBoolean(process.env.TASKFORCE_BILLING_ENABLED, false);
+    const ensureCloudBilling = (req, res) => {
+        if (!billingEnabled()) {
+            billingDisabledResponse(res);
+            return false;
+        }
+        const runtime = context.authConfig?.runtimeMode || requestRuntimeMode(req);
+        if (runtime !== 'cloud') {
+            cloudOnlyResponse(res);
+            return false;
+        }
+        return true;
+    };
+    const ensureCloudPricingRoute = (req, res) => {
+        if (!billingEnabled()) {
+            billingDisabledResponse(res);
+            return false;
+        }
+        const runtime = context.authConfig?.runtimeMode || requestRuntimeMode(req);
+        if (runtime !== 'cloud') {
+            localPricingProxyRequiredResponse(res);
+            return false;
+        }
+        return true;
+    };
+    addRoute('GET', '/api/taskforce/billing/status', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        try {
+            const userId = requestUserId(req);
+            const db = core.getDatabaseAdapter();
+            const tenantId = core.getTenantId();
+            const billingReconciliation = await reconcileBillingMirrorIfNeeded(core, userId);
+            const row = billingReconciliation.row;
+            const access = core.getAccountAccessStatus(userId);
+            if (!access.hasEntitlement || !access.entitlement) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    stripeStatus: row?.stripe_status || null,
+                    stripeCustomerId: row?.stripe_customer_id || null,
+                    stripeSubscriptionId: row?.stripe_subscription_id || null,
+                    stripePriceId: row?.stripe_price_id || null,
+                    billingInterval: row?.billing_interval || null,
+                    trialEnd: row?.trial_end || null,
+                    currentPeriodEnd: row?.current_period_end || null,
+                    effectiveUntil: row?.effective_until || null,
+                    entitlementState: null,
+                    planVersionId: null,
+                    planId: null,
+                    planName: null,
+                    gate: access.gate,
+                    message: access.message,
+                    planSelectionRequired: access.planSelectionRequired,
+                    billingConflictCode: billingReconciliation.conflictCode
+                }));
+                return;
+            }
+            const entitlement = access.entitlement;
+            const planRow = db.prepare(`
+                SELECT display_name
+                FROM plan_catalog
+                WHERE tenant_id = ? AND plan_id = ?
+                LIMIT 1
+            `).get(tenantId, entitlement.planId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                stripeStatus: row?.stripe_status || null,
+                stripeCustomerId: row?.stripe_customer_id || null,
+                stripeSubscriptionId: row?.stripe_subscription_id || null,
+                stripePriceId: row?.stripe_price_id || null,
+                billingInterval: row?.billing_interval || null,
+                trialEnd: row?.trial_end || null,
+                currentPeriodEnd: row?.current_period_end || null,
+                effectiveUntil: row?.effective_until || null,
+                entitlementState: entitlement.state,
+                planVersionId: entitlement.planVersionId,
+                planId: entitlement.planId,
+                planName: planRow?.display_name ? String(planRow.display_name) : entitlement.planId,
+                gate: access.gate,
+                message: access.message,
+                planSelectionRequired: access.planSelectionRequired,
+                billingConflictCode: billingReconciliation.conflictCode
+            }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to read billing status'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/api/taskforce/admin/billing/config', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const config = readBillingConfig(core);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(config));
+    });
+    addRoute('PUT', '/api/taskforce/admin/billing/config', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const nextConfig = {
+            tiers: body?.tiers && typeof body.tiers === 'object' && !Array.isArray(body.tiers) ? body.tiers : {},
+            taxEnabled: parseBoolean(body?.tax_enabled, false),
+            billingAddress: String(body?.billing_address || '').trim().toLowerCase() === 'required' ? 'required' : 'auto'
+        };
+        writeBillingConfig(core, nextConfig);
+        auditAdminAction(req, 'billing-config-updated', { billingAddress: nextConfig.billingAddress });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(nextConfig));
+    });
+    addRoute('GET', '/api/taskforce/admin/billing/prices', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const rows = db.prepare(`
+            SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+            FROM billing_price_mappings
+            WHERE tenant_id = ?
+            ORDER BY plan_version_id ASC, billing_interval ASC, stripe_price_id ASC
+        `).all(tenantId);
+        if (rows.length === 0) {
+            console.warn(`[Taskforce] Cloud billing returned no price mappings for tenant=${tenantId}.`);
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ prices: rows }));
+    });
+    addRoute('GET', '/api/taskforce/admin/billing/stripe-price-options', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        try {
+            const requestUrl = parseRequestUrl(req);
+            const interval = parseInterval(requestUrl.searchParams.get('interval'));
+            const options = await listStripePriceOptions(interval);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ options }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to list Stripe prices'), code: error?.code }));
+        }
+    });
+    addRoute('PUT', '/api/taskforce/admin/billing/price-mappings', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const planVersionId = String(body?.planVersionId || '').trim();
+        const interval = parseInterval(body?.interval);
+        const pricingType = parsePricingType(body?.pricingType) || 'stripe';
+        const stripePriceId = String(body?.stripePriceId || '').trim();
+        const setActive = body?.active === false ? false : true;
+        if (!planVersionId || !interval) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId and interval are required.', code: 'BILLING_MAPPING_INPUT_REQUIRED' }));
+            return;
+        }
+        if (pricingType === 'stripe' && !stripePriceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'stripePriceId is required for Stripe pricing.', code: 'BILLING_MAPPING_STRIPE_PRICE_REQUIRED' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const versionExists = db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_version_id = ?
+            LIMIT 1
+        `).get(tenantId, planVersionId);
+        if (!versionExists?.plan_version_id) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Plan version not found.', code: 'PLAN_VERSION_NOT_FOUND' }));
+            return;
+        }
+        try {
+            const now = new Date().toISOString();
+            const targetStripePriceId = pricingType === 'free'
+                ? buildFreePricingSyntheticId(planVersionId, interval)
+                : stripePriceId;
+            let unitAmount = 0;
+            let currency = null;
+            if (pricingType === 'stripe') {
+                const stripe = getStripeClient();
+                const stripePrice = await stripe.prices.retrieve(stripePriceId);
+                const stripeInterval = parseInterval(stripePrice.recurring?.interval || '');
+                if (!stripePrice.active) {
+                    res.writeHead(422, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Stripe price is not active.', code: 'STRIPE_PRICE_INACTIVE' }));
+                    return;
+                }
+                if (!stripeInterval) {
+                    res.writeHead(422, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Stripe price must be recurring month/year.', code: 'STRIPE_PRICE_INTERVAL_UNSUPPORTED' }));
+                    return;
+                }
+                if (stripeInterval !== interval) {
+                    res.writeHead(422, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `Stripe price interval (${stripeInterval}) does not match requested interval (${interval}).`, code: 'STRIPE_PRICE_INTERVAL_MISMATCH' }));
+                    return;
+                }
+                unitAmount = typeof stripePrice.unit_amount === 'number' ? stripePrice.unit_amount : null;
+                currency = stripePrice.currency || null;
+            }
+            const beforeRows = db.prepare(`
+                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+                ORDER BY stripe_price_id ASC
+            `).all(tenantId, planVersionId, interval);
+            if (setActive) {
+                db.prepare(`
+                    UPDATE billing_price_mappings
+                    SET active = 0, updated_at = ?
+                    WHERE tenant_id = ?
+                      AND plan_version_id = ?
+                      AND billing_interval = ?
+                      AND stripe_price_id <> ?
+                      AND active = 1
+                `).run(now, tenantId, planVersionId, interval, targetStripePriceId);
+            }
+            db.prepare(`
+                INSERT INTO billing_price_mappings (
+                    tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (tenant_id, plan_version_id, billing_interval, stripe_price_id) DO UPDATE SET
+                    pricing_type = excluded.pricing_type,
+                    active = excluded.active,
+                    unit_amount = excluded.unit_amount,
+                    currency = excluded.currency,
+                    updated_at = excluded.updated_at
+            `).run(tenantId, planVersionId, interval, targetStripePriceId, pricingType, setActive ? 1 : 0, unitAmount, currency, now, now);
+            const mapping = db.prepare(`
+                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ? AND stripe_price_id = ?
+                LIMIT 1
+            `).get(tenantId, planVersionId, interval, targetStripePriceId);
+            const afterRows = db.prepare(`
+                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+                ORDER BY stripe_price_id ASC
+            `).all(tenantId, planVersionId, interval);
+            auditAdminAction(req, 'billing-price-mapping-upsert', {
+                planVersionId,
+                interval,
+                pricingType,
+                stripePriceId: pricingType === 'free' ? null : stripePriceId,
+                active: setActive,
+                before: beforeRows,
+                after: afterRows
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ mapping }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to upsert price mapping'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/admin/billing/price-mappings/deactivate', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const planVersionId = String(body?.planVersionId || '').trim();
+        const interval = parseInterval(body?.interval);
+        const stripePriceId = String(body?.stripePriceId || '').trim();
+        if (!planVersionId || !interval) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId and interval are required.', code: 'BILLING_MAPPING_TARGET_REQUIRED' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const now = new Date().toISOString();
+        const beforeRows = db.prepare(`
+            SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+            FROM billing_price_mappings
+            WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+            ORDER BY stripe_price_id ASC
+        `).all(tenantId, planVersionId, interval);
+        const result = stripePriceId
+            ? db.prepare(`
+                UPDATE billing_price_mappings
+                SET active = 0, updated_at = ?
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ? AND stripe_price_id = ?
+            `).run(now, tenantId, planVersionId, interval, stripePriceId)
+            : db.prepare(`
+                UPDATE billing_price_mappings
+                SET active = 0, updated_at = ?
+                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+            `).run(now, tenantId, planVersionId, interval);
+        const afterRows = db.prepare(`
+            SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
+            FROM billing_price_mappings
+            WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
+            ORDER BY stripe_price_id ASC
+        `).all(tenantId, planVersionId, interval);
+        auditAdminAction(req, 'billing-price-mapping-deactivate', {
+            planVersionId,
+            interval,
+            stripePriceId: stripePriceId || null,
+            changedRows: Number(result?.changes || 0),
+            before: beforeRows,
+            after: afterRows
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, changedRows: Number(result?.changes || 0) }));
+    });
+    addRoute('GET', '/api/taskforce/admin/billing/webhook-failures', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const queryLimit = req.url
+            ? new URL(req.url, 'https://taskforce.local').searchParams.get('limit')
+            : null;
+        const limit = parsePositiveIntBounded(queryLimit, 50, 1, 200);
+        const now = new Date().toISOString();
+        const purged = purgeExpiredWebhookFailures(core);
+        const rows = db.prepare(`
+            SELECT id, event_id, event_type, reason, payload_excerpt, created_at, purge_after
+            FROM stripe_webhook_failures
+            WHERE tenant_id = ?
+            ORDER BY created_at DESC
+            LIMIT ?
+        `).all(tenantId, limit);
+        const total = db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM stripe_webhook_failures
+            WHERE tenant_id = ?
+        `).get(tenantId);
+        const expiringSoon = db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM stripe_webhook_failures
+            WHERE tenant_id = ?
+              AND purge_after <= ?
+        `).get(tenantId, new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString());
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            asOf: now,
+            purgedExpiredRows: purged,
+            total: Number(total?.count || 0),
+            expiringWithin24h: Number(expiringSoon?.count || 0),
+            rows
+        }));
+    });
+    addRoute('POST', '/api/taskforce/admin/billing/prices/import', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        try {
+            const summary = await importStripePrices(core);
+            auditAdminAction(req, 'billing-prices-import', {
+                imported: summary.imported,
+                skipped: summary.skipped,
+                deactivated: summary.deactivated
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(summary));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to import Stripe prices'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/__taskforce/mock-stripe/checkout', async (req, res) => {
+        if (!billingEnabled() || (context.authConfig?.runtimeMode || requestRuntimeMode(req)) !== 'cloud' || !isMockStripeEnabled()) {
+            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end('Not found');
+            return;
+        }
+        const sessionId = parseRequestUrl(req).searchParams.get('session_id') || '';
+        const session = readMockStripeCheckoutSession(sessionId);
+        if (!session) {
+            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end('Mock checkout session not found.');
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(renderMockStripeCheckoutHtml({
+            sessionId: session.id,
+            planVersionId: session.subscriptionMetadata.planVersionId || session.subscriptionMetadata.plan_version_id || null,
+            interval: session.interval
+        }));
+    });
+    addRoute('GET', '/__taskforce/mock-stripe/checkout/complete', async (req, res) => {
+        if (!billingEnabled() || (context.authConfig?.runtimeMode || requestRuntimeMode(req)) !== 'cloud' || !isMockStripeEnabled()) {
+            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end('Not found');
+            return;
+        }
+        const sessionId = parseRequestUrl(req).searchParams.get('session_id') || '';
+        try {
+            const session = completeMockStripeCheckoutSession(sessionId);
+            const nextUrl = String(session.successUrl || '').replace('{CHECKOUT_SESSION_ID}', encodeURIComponent(session.id));
+            res.writeHead(302, { Location: nextUrl || '/' });
+            res.end();
+        }
+        catch (error) {
+            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end(String(error?.message || 'Mock checkout session not found.'));
+        }
+    });
+    addRoute('GET', '/__taskforce/mock-stripe/checkout/cancel', async (req, res) => {
+        if (!billingEnabled() || (context.authConfig?.runtimeMode || requestRuntimeMode(req)) !== 'cloud' || !isMockStripeEnabled()) {
+            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end('Not found');
+            return;
+        }
+        const sessionId = parseRequestUrl(req).searchParams.get('session_id') || '';
+        const session = readMockStripeCheckoutSession(sessionId);
+        res.writeHead(302, {
+            Location: String(session?.cancelUrl || '/')
+        });
+        res.end();
+    });
+    addRoute('POST', '/api/taskforce/billing/checkout-session', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const interval = parseInterval(body?.interval);
+        const planVersionId = String(body?.planVersionId || '').trim();
+        if (!interval || !planVersionId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId and interval are required.' }));
+            return;
+        }
+        const pricing = resolveActivePricingForPlanVersion(core, planVersionId, interval);
+        if (!pricing) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No active pricing mapping found for requested plan/interval.' }));
+            return;
+        }
+        try {
+            const userId = requestUserId(req);
+            const currentBillingResult = await reconcileBillingMirrorIfNeeded(core, userId);
+            const currentBilling = currentBillingResult.row;
+            if (currentBillingResult.conflictCode === 'BILLING_DUPLICATE_ACTIVE_SUBSCRIPTIONS') {
+                console.warn(`[Taskforce Billing] Duplicate active subscriptions detected for user=${userId}`);
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Multiple active subscriptions are already linked to this account. Please contact support before making changes.',
+                    code: currentBillingResult.conflictCode
+                }));
+                return;
+            }
+            const currentEntitlement = getEntitlementRow(core, userId);
+            const userIdentity = core.resolveUserIdentity(userId);
+            const normalizedUserEmail = normalizeEmail(userIdentity?.email);
+            if (pricing.pricingType === 'free') {
+                if (currentEntitlement?.plan_version_id && String(currentEntitlement.plan_version_id).trim() === planVersionId) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        checkoutState: 'already_current_plan',
+                        planVersionId,
+                        message: 'You are already on this plan.'
+                    }));
+                    return;
+                }
+                const billingProfile = core.getBillingMirrorProfileForPlanVersion(planVersionId);
+                core.createUserBillingRecord(userId, billingProfile);
+                core.updateAccountEntitlement({
+                    accountId: userId,
+                    planVersionId,
+                    entitlementState: 'active',
+                    actorUserId: userId,
+                    actorRole: 'user',
+                    reason: 'free-plan-selection'
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ checkoutState: 'free', planVersionId }));
+                return;
+            }
+            const priceId = pricing.stripePriceId;
+            if (!priceId) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'No active Stripe price mapping found for requested plan/interval.' }));
+                return;
+            }
+            const stripe = getStripeClient();
+            let currentSubscriptionId = String(currentBilling?.stripe_subscription_id || '').trim();
+            const currentCustomerId = String(currentBilling?.stripe_customer_id || '').trim();
+            const currentPlanVersionId = String(currentEntitlement?.plan_version_id || '').trim();
+            const currentInterval = parseInterval(String(currentBilling?.billing_interval || '').trim());
+            const stripeAccountDiscovery = await discoverStripeAccountStateForUser(core, {
+                userId,
+                normalizedEmail: normalizedUserEmail,
+                currentCustomerId
+            });
+            if (stripeAccountDiscovery.activeSubscriptions.length > 1) {
+                console.warn(`[Taskforce Billing] Duplicate active subscriptions detected for user=${userId}`);
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Multiple active subscriptions are already linked to this account. Please contact support before making changes.',
+                    code: 'BILLING_DUPLICATE_ACTIVE_SUBSCRIPTIONS'
+                }));
+                return;
+            }
+            let resolvedCustomerId = currentCustomerId || String(stripeAccountDiscovery.preferredCustomerId || '').trim();
+            if (!currentSubscriptionId && stripeAccountDiscovery.activeSubscriptions.length === 1) {
+                const activeSubscription = stripeAccountDiscovery.activeSubscriptions[0];
+                currentSubscriptionId = String(activeSubscription.subscription?.id || '').trim();
+                resolvedCustomerId = String(activeSubscription.customerId || '').trim() || resolvedCustomerId;
+                if (currentSubscriptionId || resolvedCustomerId) {
+                    upsertBillingMirror(core, {
+                        userId,
+                        stripeCustomerId: resolvedCustomerId || null,
+                        stripeSubscriptionId: currentSubscriptionId || null
+                    });
+                }
+            }
+            else if (!currentCustomerId && resolvedCustomerId) {
+                upsertBillingMirror(core, {
+                    userId,
+                    stripeCustomerId: resolvedCustomerId
+                });
+            }
+            if (currentSubscriptionId && currentPlanVersionId === planVersionId && currentInterval === interval) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    checkoutState: 'already_current_plan',
+                    planVersionId,
+                    message: 'You are already on this plan.'
+                }));
+                return;
+            }
+            if (currentSubscriptionId) {
+                const current = await stripe.subscriptions.retrieve(currentSubscriptionId);
+                const itemId = current.items.data[0]?.id;
+                if (!itemId) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Subscription has no updatable line item.' }));
+                    return;
+                }
+                const updated = await stripe.subscriptions.update(currentSubscriptionId, {
+                    items: [{ id: itemId, price: priceId }],
+                    proration_behavior: 'create_prorations',
+                    metadata: {
+                        userId,
+                        tenantId: core.getTenantId(),
+                        planVersionId,
+                        billingInterval: interval
+                    }
+                });
+                applySubscriptionSnapshot(core, {
+                    userId,
+                    subscription: updated,
+                    source: 'checkout-confirm'
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    checkoutState: 'updated',
+                    planVersionId,
+                    message: 'Your subscription was updated successfully.'
+                }));
+                return;
+            }
+            const baseUrl = resolveBaseUrl(req);
+            const config = readBillingConfig(core);
+            const planId = resolvePlanIdForVersion(core, planVersionId);
+            const selectedVersion = planId
+                ? core.listPlanVersions(planId).find((version) => version.planVersionId === planVersionId) || null
+                : null;
+            const cancelParams = new URLSearchParams({
+                screen: 'plans',
+                checkout: 'cancel',
+                planId: String(planId || ''),
+                planVersionId,
+                interval
+            });
+            const session = await stripe.checkout.sessions.create({
+                mode: 'subscription',
+                line_items: [{ price: priceId, quantity: 1 }],
+                success_url: `${baseUrl}/?screen=plans&checkout=success&session_id={CHECKOUT_SESSION_ID}`,
+                cancel_url: `${baseUrl}/?${cancelParams.toString()}`,
+                ...(resolvedCustomerId
+                    ? { customer: resolvedCustomerId }
+                    : (normalizedUserEmail ? { customer_email: normalizedUserEmail } : {})),
+                subscription_data: {
+                    ...(selectedVersion && selectedVersion.trialDays > 0 ? { trial_period_days: selectedVersion.trialDays } : {}),
+                    metadata: {
+                        userId,
+                        tenantId: core.getTenantId(),
+                        planVersionId,
+                        billingInterval: interval
+                    }
+                },
+                billing_address_collection: config.billingAddress,
+                automatic_tax: { enabled: config.taxEnabled },
+                client_reference_id: userId,
+                metadata: {
+                    userId,
+                    tenantId: core.getTenantId(),
+                    planVersionId,
+                    billingInterval: interval
+                }
+            });
+            const checkoutUrl = isMockStripeClient(stripe)
+                ? buildMockStripeHostedCheckoutUrl(resolveHostedServerBaseUrl(req), session.id)
+                : (session.url || null);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                checkoutState: 'checkout',
+                url: checkoutUrl,
+                id: session.id,
+                returnBaseUrl: baseUrl
+            }));
+        }
+        catch (error) {
+            if (isMissingStripeCustomerError(error)) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'The saved Stripe customer for this account could not be found. Please contact support before retrying checkout.',
+                    code: 'BILLING_STRIPE_CUSTOMER_MISSING'
+                }));
+                return;
+            }
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to create checkout session'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/checkout-session/confirm', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const sessionId = String(body?.sessionId || '').trim();
+        if (!sessionId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'sessionId is required.' }));
+            return;
+        }
+        try {
+            const stripe = getStripeClient();
+            const expectedUserId = requestUserId(req);
+            const session = await stripe.checkout.sessions.retrieve(sessionId, {
+                expand: ['subscription']
+            });
+            const metadata = session.metadata || {};
+            const customerId = String(session.customer || '').trim();
+            const subscriptionId = typeof session.subscription === 'string'
+                ? session.subscription.trim()
+                : String(session.subscription?.id || '').trim();
+            const resolvedUserId = String(metadata.userId || metadata.user_id || '').trim()
+                || resolveUserIdByCustomer(core, customerId)
+                || resolveUserIdBySubscription(core, subscriptionId);
+            if (!resolvedUserId) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Unable to resolve checkout session to an account.' }));
+                return;
+            }
+            if (resolvedUserId !== expectedUserId) {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Checkout session does not belong to the current account.' }));
+                return;
+            }
+            core.createUserBillingRecord(resolvedUserId);
+            upsertBillingMirror(core, {
+                userId: resolvedUserId,
+                stripeCustomerId: customerId || null,
+                stripeSubscriptionId: subscriptionId || null
+            });
+            let resolvedPlanVersionId = null;
+            if (session.mode === 'subscription' && subscriptionId) {
+                const subscription = typeof session.subscription === 'string' || !session.subscription
+                    ? await stripe.subscriptions.retrieve(subscriptionId)
+                    : session.subscription;
+                resolvedPlanVersionId = applySubscriptionSnapshot(core, {
+                    userId: resolvedUserId,
+                    subscription,
+                    source: 'checkout-confirm'
+                }).planVersionId;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: true,
+                sessionId,
+                planVersionId: resolvedPlanVersionId
+            }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to confirm checkout session'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/portal-session', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const userId = requestUserId(req);
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const row = db.prepare(`
+            SELECT stripe_customer_id
+            FROM user_billing
+            WHERE tenant_id = ? AND user_id = ?
+            LIMIT 1
+        `).get(tenantId, userId);
+        let customerId = String(row?.stripe_customer_id || '').trim();
+        if (!customerId) {
+            const userIdentity = core.resolveUserIdentity(userId);
+            const discovery = await discoverStripeAccountStateForUser(core, {
+                userId,
+                normalizedEmail: userIdentity?.email,
+                currentCustomerId: null
+            });
+            if (discovery.activeSubscriptions.length > 1) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Multiple active subscriptions are already linked to this account. Please contact support before opening the billing portal.',
+                    code: 'BILLING_DUPLICATE_ACTIVE_SUBSCRIPTIONS'
+                }));
+                return;
+            }
+            customerId = String(discovery.preferredCustomerId || '').trim();
+            if (customerId) {
+                upsertBillingMirror(core, {
+                    userId,
+                    stripeCustomerId: customerId
+                });
+            }
+        }
+        if (!customerId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No Stripe customer is linked for this account.' }));
+            return;
+        }
+        try {
+            const stripe = getStripeClient();
+            const baseUrl = resolveBaseUrl(req);
+            const session = await stripe.billingPortal.sessions.create({
+                customer: customerId,
+                return_url: `${baseUrl}/settings`
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ url: session.url, returnBaseUrl: baseUrl }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to create portal session'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/subscription', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const interval = parseInterval(body?.interval);
+        const planVersionId = String(body?.planVersionId || '').trim();
+        if (!interval || !planVersionId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'planVersionId and interval are required.' }));
+            return;
+        }
+        const nextPriceId = resolveStripePriceIdForPlanVersion(core, planVersionId, interval);
+        if (!nextPriceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No active Stripe price mapping found for requested plan/interval.' }));
+            return;
+        }
+        const userId = requestUserId(req);
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const row = db.prepare(`
+            SELECT stripe_subscription_id
+            FROM user_billing
+            WHERE tenant_id = ? AND user_id = ?
+            LIMIT 1
+        `).get(tenantId, userId);
+        const subscriptionId = String(row?.stripe_subscription_id || '').trim();
+        if (!subscriptionId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No Stripe subscription is linked for this account.' }));
+            return;
+        }
+        try {
+            const stripe = getStripeClient();
+            const current = await stripe.subscriptions.retrieve(subscriptionId);
+            const itemId = current.items.data[0]?.id;
+            if (!itemId) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Subscription has no updatable line item.' }));
+                return;
+            }
+            const updated = await stripe.subscriptions.update(subscriptionId, {
+                items: [{ id: itemId, price: nextPriceId }],
+                proration_behavior: 'create_prorations',
+                metadata: {
+                    planVersionId
+                }
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ subscription: updated }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to update subscription'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/billing/webhook', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        const webhookSecret = String(process.env.TASKFORCE_STRIPE_WEBHOOK_SECRET || '').trim();
+        if (!webhookSecret) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'TASKFORCE_STRIPE_WEBHOOK_SECRET is not configured.' }));
+            return;
+        }
+        const signature = String(req.headers['stripe-signature'] || '').trim();
+        if (!signature) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing Stripe signature.' }));
+            return;
+        }
+        let event;
+        let rawBody;
+        try {
+            rawBody = await readRawBody(req);
+            const stripe = getStripeClient();
+            event = stripe.webhooks.constructEvent(rawBody, signature, webhookSecret);
+        }
+        catch (error) {
+            const code = Number(error?.statusCode || 400);
+            res.writeHead(code >= 400 && code < 600 ? code : 400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Invalid webhook payload/signature') }));
+            return;
+        }
+        try {
+            const db = core.getDatabaseAdapter();
+            const tenantId = core.getTenantId();
+            purgeExpiredWebhookFailures(core);
+            let duplicate = false;
+            const tx = db.transaction(() => {
+                const acquired = lockWebhookEvent(core, event);
+                if (!acquired) {
+                    duplicate = true;
+                    return;
+                }
+                if (event.type === 'checkout.session.completed') {
+                    const session = event.data.object;
+                    const metadata = session.metadata || {};
+                    const customerId = String(session.customer || '').trim();
+                    const subscriptionId = String(session.subscription || '').trim();
+                    const userId = String(metadata.userId || metadata.user_id || '').trim()
+                        || resolveUserIdByCustomer(core, customerId)
+                        || resolveUserIdBySubscription(core, subscriptionId);
+                    if (!userId || !customerId) {
+                        throw new Error('Unable to link checkout completion to user/customer.');
+                    }
+                    core.createUserBillingRecord(userId);
+                    upsertBillingMirror(core, {
+                        userId,
+                        stripeCustomerId: customerId,
+                        stripeSubscriptionId: subscriptionId || null
+                    });
+                    return;
+                }
+                if (event.type === 'customer.subscription.created' || event.type === 'customer.subscription.updated' || event.type === 'customer.subscription.deleted') {
+                    const subscription = event.data.object;
+                    const customerId = String(subscription.customer || '').trim();
+                    const userId = resolveUserIdByCustomer(core, customerId)
+                        || String(subscription.metadata?.userId || subscription.metadata?.user_id || '').trim();
+                    if (!userId) {
+                        throw new Error('Unable to resolve user for subscription event.');
+                    }
+                    core.createUserBillingRecord(userId);
+                    const priceId = String(subscription.items?.data?.[0]?.price?.id || '').trim();
+                    const planVersionResolution = resolvePlanVersionIdForBillingEvent(core, [
+                        subscription.metadata?.planVersionId,
+                        subscription.metadata?.plan_version_id
+                    ], priceId);
+                    const planVersionId = planVersionResolution.planVersionId;
+                    if (!planVersionId) {
+                        recordWebhookFailure(core, {
+                            eventId: event.id,
+                            eventType: event.type,
+                            reason: planVersionResolution.reason === 'ambiguous'
+                                ? `Ambiguous price mapping for price_id=${priceId || '(empty)'}`
+                                : `Unknown price mapping for price_id=${priceId || '(empty)'}`,
+                            payload: event
+                        });
+                        return;
+                    }
+                    applySubscriptionSnapshot(core, {
+                        userId,
+                        subscription,
+                        source: 'stripe-webhook'
+                    });
+                    return;
+                }
+                if (event.type === 'invoice.paid' || event.type === 'invoice.payment_failed') {
+                    const invoice = event.data.object;
+                    const customerId = String(invoice.customer || '').trim();
+                    const subscriptionId = resolveInvoiceSubscriptionId(invoice);
+                    const userId = resolveUserIdByCustomer(core, customerId)
+                        || resolveUserIdBySubscription(core, subscriptionId);
+                    if (!userId) {
+                        throw new Error('Unable to resolve user for invoice event.');
+                    }
+                    core.createUserBillingRecord(userId);
+                    const { priceId, interval } = resolvePriceAndIntervalFromInvoice(invoice);
+                    const planVersionResolution = resolvePlanVersionIdForBillingEvent(core, [
+                        invoice.parent?.subscription_details?.metadata?.planVersionId,
+                        invoice.parent?.subscription_details?.metadata?.plan_version_id,
+                        invoice.subscription_details?.metadata?.planVersionId,
+                        invoice.subscription_details?.metadata?.plan_version_id
+                    ], priceId);
+                    const planVersionId = planVersionResolution.planVersionId;
+                    const existingEntitlement = getEntitlementRow(core, userId);
+                    const canonicalState = event.type === 'invoice.payment_failed' ? 'grace' : 'active';
+                    const currentPeriodEnd = invoice.lines?.data?.[0]?.period?.end
+                        ? isoFromUnixSeconds(invoice.lines.data[0].period.end)
+                        : null;
+                    upsertBillingMirror(core, {
+                        userId,
+                        stripeCustomerId: customerId || null,
+                        stripeSubscriptionId: subscriptionId || null,
+                        stripePriceId: priceId || null,
+                        stripeStatus: event.type === 'invoice.payment_failed' ? 'past_due' : 'active',
+                        planId: planVersionId ? resolvePlanIdForVersion(core, planVersionId) : null,
+                        billingInterval: interval || null,
+                        canonicalState,
+                        currentPeriodEnd,
+                        effectiveUntil: currentPeriodEnd
+                    });
+                    if (!planVersionId) {
+                        recordWebhookFailure(core, {
+                            eventId: event.id,
+                            eventType: event.type,
+                            reason: planVersionResolution.reason === 'ambiguous'
+                                ? `Ambiguous price mapping for price_id=${priceId || '(empty)'}`
+                                : `Unknown price mapping for price_id=${priceId || '(empty)'}`,
+                            payload: event
+                        });
+                        return;
+                    }
+                    upsertCanonicalEntitlement(core, {
+                        userId,
+                        planVersionId: planVersionId || existingEntitlement?.plan_version_id || core.getDefaultPlanVersionIdByMode('personal', { allowFallback: true }),
+                        state: canonicalState,
+                        effectiveAt: new Date().toISOString(),
+                        effectiveUntil: currentPeriodEnd
+                    });
+                    return;
+                }
+            });
+            tx();
+            if (duplicate) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ received: true, duplicate: true }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ received: true }));
+        }
+        catch (error) {
+            recordWebhookFailure(core, {
+                eventId: event.id,
+                eventType: event.type,
+                reason: String(error?.message || error || 'WEBHOOK_PROCESSING_FAILED'),
+                payload: event
+            });
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Webhook processing failed. Retry expected.' }));
+        }
+    });
+    addRoute('GET', '/api/taskforce/public/pricing', async (req, res) => {
+        if (!ensureCloudPricingRoute(req, res))
+            return;
+        try {
+            const db = core.getDatabaseAdapter();
+            const tenantId = core.getTenantId();
+            // Get all active plans
+            const activePlans = core.listPlanCatalog().filter(p => p.status === 'active');
+            // Get all active price mappings with their amounts
+            const activePrices = db.prepare(`
+                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, unit_amount, currency
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND active = 1
+            `).all(tenantId);
+            const plansPayload = activePlans.map((plan) => {
+                const versions = core.listPlanVersions(plan.planId);
+                // Prefer default, else fallback to highest version number
+                const defaultVersion = versions.find(v => v.isDefault) || [...versions].sort((a, b) => b.versionNumber - a.versionNumber)[0];
+                if (!defaultVersion) {
+                    return null; // Skip if no valid version exists (edge case)
+                }
+                const monthPrice = activePrices.find(p => p.plan_version_id === defaultVersion.planVersionId && p.billing_interval === 'month');
+                const yearPrice = activePrices.find(p => p.plan_version_id === defaultVersion.planVersionId && p.billing_interval === 'year');
+                return {
+                    planId: plan.planId,
+                    displayName: plan.displayName,
+                    status: plan.status,
+                    defaultVersion: {
+                        planVersionId: defaultVersion.planVersionId,
+                        versionNumber: defaultVersion.versionNumber,
+                        seatLimit: defaultVersion.seatLimit,
+                        trialDays: defaultVersion.trialDays,
+                        metadata: defaultVersion.metadata
+                    },
+                    features: Object.values(defaultVersion.features || {}).filter((feature) => {
+                        const access = String(feature?.access || '').trim().toLowerCase();
+                        return access !== 'disabled';
+                    }),
+                    pricing: {
+                        month: monthPrice ? {
+                            pricingType: parsePricingType(monthPrice.pricing_type) || 'stripe',
+                            stripePriceId: (parsePricingType(monthPrice.pricing_type) || 'stripe') === 'stripe' ? monthPrice.stripe_price_id : null,
+                            unitAmount: (parsePricingType(monthPrice.pricing_type) || 'stripe') === 'free' ? 0 : monthPrice.unit_amount,
+                            currency: (parsePricingType(monthPrice.pricing_type) || 'stripe') === 'free' ? null : monthPrice.currency,
+                            interval: 'month'
+                        } : null,
+                        year: yearPrice ? {
+                            pricingType: parsePricingType(yearPrice.pricing_type) || 'stripe',
+                            stripePriceId: (parsePricingType(yearPrice.pricing_type) || 'stripe') === 'stripe' ? yearPrice.stripe_price_id : null,
+                            unitAmount: (parsePricingType(yearPrice.pricing_type) || 'stripe') === 'free' ? 0 : yearPrice.unit_amount,
+                            currency: (parsePricingType(yearPrice.pricing_type) || 'stripe') === 'free' ? null : yearPrice.currency,
+                            interval: 'year'
+                        } : null
+                    }
+                };
+            }).filter(Boolean);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                asOf: new Date().toISOString(),
+                pricingSource: {
+                    environment: requestPricingEnvironment(req),
+                    runtimeMode: 'cloud'
+                },
+                plans: plansPayload
+            }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 500);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to fetch pricing'), code: error?.code }));
+        }
+    });
+}