@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/server/routes/authSupport.d.ts

@@ -0,0 +1,30 @@
+import type { IncomingMessage } from 'http';
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import type { RouteContext } from './primitives.js';
+export declare function resolveBooleanSetting(value: unknown, fallback: boolean): boolean;
+export declare function getRouteEmailConfig(core: TaskforceCore, context: RouteContext): import("../email.js").TaskforceEmailConfig;
+export declare function buildAuthFlowBehavior(core: TaskforceCore): {
+    allowSelfRegistration: boolean;
+    requireVerifiedEmail: boolean;
+    defaultNewUserBetaAccess: boolean;
+    authRateLimitEnabled: boolean;
+    authRateLimitMaxRequests: number;
+    authRateLimitWindowMs: number;
+};
+export declare function buildAuthBehavior(core: TaskforceCore): {
+    onboardingPolicyMode: import("../../core/types.js").OnboardingPolicyMode;
+    onboardingPlanId: string | null;
+    allowSelfRegistration: boolean;
+    requireVerifiedEmail: boolean;
+    defaultNewUserBetaAccess: boolean;
+    authRateLimitEnabled: boolean;
+    authRateLimitMaxRequests: number;
+    authRateLimitWindowMs: number;
+};
+export declare function buildSiteBehavior(core: TaskforceCore): {
+    showRunTaskforceLocally: boolean;
+    pricingPageEnabled: boolean;
+};
+export declare function shouldExposeDevAuthTokens(): boolean;
+export declare function resolveRuntimeConfigBaseUrl(req: IncomingMessage): string;
+export declare function resolvePublicAuthBaseUrl(req: IncomingMessage): string;

package/dist/server/routes/authSupport.js

@@ -0,0 +1,81 @@
+import { resolveEffectiveEmailConfig } from '../email.js';
+import { resolveDeploymentConfig } from '../../config/deployment.js';
+export function resolveBooleanSetting(value, fallback) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    const normalized = String(value || '').trim().toLowerCase();
+    if (!normalized)
+        return fallback;
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    return fallback;
+}
+export function getRouteEmailConfig(core, context) {
+    if (context.authConfig?.runtimeMode !== 'cloud') {
+        return resolveEffectiveEmailConfig(process.env, { provider: 'console' });
+    }
+    const globalSettings = core.getGlobalSettings();
+    return resolveEffectiveEmailConfig(process.env, globalSettings.email || null);
+}
+export function buildAuthFlowBehavior(core) {
+    const globalSettings = core.getGlobalSettings();
+    const authSettings = globalSettings.auth || {};
+    const authRateLimitMaxRequestsRaw = Number(authSettings.authRateLimitMaxRequests);
+    const authRateLimitWindowMsRaw = Number(authSettings.authRateLimitWindowMs);
+    return {
+        allowSelfRegistration: resolveBooleanSetting(authSettings.allowSelfRegistration, true),
+        requireVerifiedEmail: resolveBooleanSetting(authSettings.requireVerifiedEmail, true),
+        defaultNewUserBetaAccess: resolveBooleanSetting(authSettings.defaultNewUserBetaAccess, false),
+        authRateLimitEnabled: resolveBooleanSetting(authSettings.authRateLimitEnabled, true),
+        authRateLimitMaxRequests: Number.isFinite(authRateLimitMaxRequestsRaw) && authRateLimitMaxRequestsRaw >= 1
+            ? Math.floor(authRateLimitMaxRequestsRaw)
+            : 10,
+        authRateLimitWindowMs: Number.isFinite(authRateLimitWindowMsRaw) && authRateLimitWindowMsRaw >= 1000
+            ? Math.floor(authRateLimitWindowMsRaw)
+            : 15 * 60_000,
+    };
+}
+export function buildAuthBehavior(core) {
+    const authBehavior = buildAuthFlowBehavior(core);
+    const onboardingPolicy = core.getOnboardingPolicy();
+    return {
+        ...authBehavior,
+        onboardingPolicyMode: onboardingPolicy.mode,
+        onboardingPlanId: onboardingPolicy.planId
+    };
+}
+export function buildSiteBehavior(core) {
+    const globalSettings = core.getGlobalSettings();
+    const siteSettings = globalSettings.site || {};
+    return {
+        showRunTaskforceLocally: resolveBooleanSetting(siteSettings.showRunTaskforceLocally, true),
+        pricingPageEnabled: resolveBooleanSetting(siteSettings.pricingPageEnabled, true)
+    };
+}
+export function shouldExposeDevAuthTokens() {
+    const explicit = String(process.env.TASKFORCE_AUTH_EXPOSE_DEV_TOKENS || '').trim().toLowerCase();
+    return explicit === '1' || explicit === 'true' || explicit === 'yes';
+}
+export function resolveRuntimeConfigBaseUrl(req) {
+    const host = String(req.headers['x-forwarded-host'] || req.headers.host || '').trim();
+    if (!host)
+        return '';
+    const proto = String(req.headers['x-forwarded-proto'] || '').trim().toLowerCase() === 'https'
+        ? 'https'
+        : (req.socket?.encrypted ? 'https' : 'http');
+    return `${proto}://${host}`.replace(/\/+$/, '');
+}
+export function resolvePublicAuthBaseUrl(req) {
+    const configured = String(process.env.TASKFORCE_AUTH_PUBLIC_BASE_URL || '').trim().replace(/\/+$/, '');
+    if (configured)
+        return configured;
+    const host = String(req.headers['x-forwarded-host'] || req.headers.host || '').trim();
+    const proto = String(req.headers['x-forwarded-proto'] || '').trim().toLowerCase() === 'http' ? 'http' : 'https';
+    if (!host)
+        return resolveDeploymentConfig(process.env).cloudBaseUrl || 'https://app.taskforcehq.ai';
+    return `${proto}://${host}`;
+}

package/dist/server/routes/billing.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage } from 'http';
 import type { TaskforceCore } from '../../core/Taskforce.js';
-import type { RouteHandler, RouteContext } from '../routes.js';
+import { type RouteHandler, type RouteContext } from './primitives.js';
 export type BillingInterval = 'month' | 'year';
 export type BillingPricingType = 'stripe' | 'free';
 export interface BillingRouteDependencies {

package/dist/server/routes/billing.js

@@ -1,5 +1,5 @@
 import Stripe from 'stripe';
-import { parseJsonBody } from '../routes.js';
+import { parseJsonBody } from './primitives.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';
@@ -8,16 +8,63 @@ const BILLING_DIAGNOSTIC_RETENTION_DAYS = 30;
 const BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES = 8 * 1024;
 const BILLING_CHECKOUT_ATTEMPT_RETENTION_DAYS = 14;
 const BILLING_STATUS_RECONCILIATION_TTL_MS = 30_000;
+const PUBLIC_PRICING_CACHE_TTL_MS = 60_000;
 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';
+const INTERNAL_PUBLIC_PRICING_FEATURE_KEYS = new Set([
+    'collaboration.invites',
+    'collaboration.seat_limit'
+]);
+const publicPricingCache = new Map();
 function parsePricingType(raw) {
     const value = String(raw || '').trim().toLowerCase();
     if (value === 'stripe' || value === 'free')
         return value;
     return null;
 }
+function readTableVersionStats(core, tableName) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    try {
+        const row = db.prepare(`
+            SELECT COUNT(*) AS count, MAX(updated_at) AS max_updated_at
+            FROM ${tableName}
+            WHERE tenant_id = ?
+        `).get(tenantId);
+        return {
+            count: Number(row?.count || 0),
+            maxUpdatedAt: String(row?.max_updated_at || '')
+        };
+    }
+    catch (error) {
+        const message = String(error?.message || '');
+        if (message.toLowerCase().includes(`no such table: ${tableName}`)) {
+            return { count: 0, maxUpdatedAt: '' };
+        }
+        throw error;
+    }
+}
+function buildPublicPricingCacheVersion(core) {
+    const catalog = readTableVersionStats(core, 'plan_catalog');
+    const versions = readTableVersionStats(core, 'plan_versions');
+    const prices = readTableVersionStats(core, 'billing_price_mappings');
+    const features = readTableVersionStats(core, 'plan_feature_matrix');
+    const featureCatalogOverrides = readTableVersionStats(core, 'plan_feature_catalog_overrides');
+    return [
+        catalog.count,
+        catalog.maxUpdatedAt,
+        versions.count,
+        versions.maxUpdatedAt,
+        prices.count,
+        prices.maxUpdatedAt,
+        features.count,
+        features.maxUpdatedAt,
+        featureCatalogOverrides.count,
+        featureCatalogOverrides.maxUpdatedAt
+    ].join('|');
+}
 function buildFreePricingSyntheticId(planVersionId, interval) {
     return `free:${planVersionId}:${interval}`;
 }
@@ -664,7 +711,11 @@ function resolveCheckoutLifecycleGuard(core, input) {
         : currentOpenAttempt;
     const attemptStatus = String(checkoutAttempt?.status || '').trim().toLowerCase();
     const attemptPlanVersionId = String(checkoutAttempt?.plan_version_id || '').trim();
+    const sourceLabel = String(input.source || 'checkout-confirm').trim() || 'checkout-confirm';
     if (attemptStatus === 'expired') {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked expired checkout for user=${input.userId} source=${sourceLabel} `
+            + `session=${String(input.sessionId || '').trim() || '(none)'} subscription=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} attemptPlanVersionId=${attemptPlanVersionId || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_EXPIRED',
@@ -672,6 +723,9 @@ function resolveCheckoutLifecycleGuard(core, input) {
         };
     }
     if (attemptStatus === 'superseded') {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked superseded checkout for user=${input.userId} source=${sourceLabel} `
+            + `session=${String(input.sessionId || '').trim() || '(none)'} subscription=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} attemptPlanVersionId=${attemptPlanVersionId || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -679,6 +733,9 @@ function resolveCheckoutLifecycleGuard(core, input) {
         };
     }
     if (attemptStatus === 'open' && attemptPlanVersionId && input.planVersionId && attemptPlanVersionId !== input.planVersionId) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked mismatched open checkout for user=${input.userId} source=${sourceLabel} `
+            + `session=${String(input.sessionId || '').trim() || '(none)'} subscription=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} attemptPlanVersionId=${attemptPlanVersionId}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -688,6 +745,9 @@ function resolveCheckoutLifecycleGuard(core, input) {
     const currentBilling = getBillingMirrorRow(core, input.userId);
     const currentSubscriptionId = String(currentBilling?.stripe_subscription_id || '').trim();
     if (!currentOpenAttempt && input.subscriptionId && currentSubscriptionId && currentSubscriptionId !== input.subscriptionId) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked stale subscription linkage for user=${input.userId} source=${sourceLabel} `
+            + `currentSubscriptionId=${currentSubscriptionId} requestedSubscriptionId=${String(input.subscriptionId || '').trim() || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -701,17 +761,28 @@ function resolveCheckoutLifecycleGuard(core, input) {
     const currentPlanVersionId = String(entitlement.plan_version_id || '').trim();
     const updatedBy = String(entitlement.updated_by || '').trim().toLowerCase();
     const expiredPendingCheckout = currentState === 'checkout_pending' && isIsoTimestampExpired(entitlement.effective_until);
-    if (expiredPendingCheckout || (currentState === 'pending_plan_selection' && updatedBy === 'checkout-expired')) {
+    const fromStripeWebhook = input.source === 'stripe-webhook';
+    if (!fromStripeWebhook && (expiredPendingCheckout || (currentState === 'pending_plan_selection' && updatedBy === 'checkout-expired'))) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked expired entitlement recovery for user=${input.userId} source=${sourceLabel} `
+            + `entitlementState=${currentState || '(none)'} updatedBy=${updatedBy || '(none)'} `
+            + `requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} currentPlanVersionId=${currentPlanVersionId || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_EXPIRED',
             message: 'This checkout session expired. Choose a plan and start checkout again.'
         };
     }
+    if (fromStripeWebhook && (expiredPendingCheckout || (currentState === 'pending_plan_selection' && updatedBy === 'checkout-expired'))) {
+        console.info(`[Taskforce Billing] Lifecycle guard allowed authoritative webhook recovery for user=${input.userId} `
+            + `subscription=${String(input.subscriptionId || '').trim() || '(none)'} requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'} `
+            + `entitlementState=${currentState || '(none)'} updatedBy=${updatedBy || '(none)'}`);
+    }
     if (currentState === 'checkout_pending'
         && currentPlanVersionId
         && input.planVersionId
         && currentPlanVersionId !== input.planVersionId) {
+        console.warn(`[Taskforce Billing] Lifecycle guard blocked superseded checkout_pending entitlement for user=${input.userId} source=${sourceLabel} `
+            + `currentPlanVersionId=${currentPlanVersionId} requestedPlanVersionId=${String(input.planVersionId || '').trim() || '(none)'}`);
         return {
             blocked: true,
             code: 'CHECKOUT_SESSION_SUPERSEDED',
@@ -795,11 +866,15 @@ function applySubscriptionSnapshot(core, input) {
         ? (currentPeriodEnd && currentPeriodEnd > nowIso ? 'active' : 'canceled')
         : null;
     const mappedCanonicalState = canceledState || mapStripeStatusToCanonicalState(stripeStatus);
+    const existingPlanVersionId = String(existingEntitlement?.plan_version_id || '').trim();
     const preserveExistingAccess = mappedCanonicalState === 'checkout_pending'
+        && Boolean(planVersionId)
+        && existingPlanVersionId === planVersionId
         && isCommercialStateAppAccessible(existingEntitlement?.entitlement_state);
     const canonicalState = preserveExistingAccess
         ? String(existingEntitlement?.entitlement_state || 'active').trim().toLowerCase()
         : mappedCanonicalState;
+    const billingConfirmedSource = source === 'stripe-webhook' || source === 'checkout-confirm';
     const effectiveUntil = stripeStatus === 'canceled'
         ? currentPeriodEnd
         : (currentPeriodEnd || null);
@@ -826,7 +901,7 @@ function applySubscriptionSnapshot(core, input) {
             });
         }
     }
-    else if (planVersionId) {
+    else if (planVersionId && billingConfirmedSource) {
         core.transitionCanonicalCommercialState({
             accountId: userId,
             planVersionId: planVersionId || existingEntitlement?.plan_version_id || core.getDefaultPlanVersionIdByMode('personal', { allowFallback: true }),
@@ -1402,6 +1477,23 @@ export function registerBillingRoutes(deps) {
                     res.end(JSON.stringify({ error: `Stripe price interval (${stripeInterval}) does not match requested interval (${interval}).`, code: 'STRIPE_PRICE_INTERVAL_MISMATCH' }));
                     return;
                 }
+                const conflictingMapping = db.prepare(`
+                    SELECT plan_version_id
+                    FROM billing_price_mappings
+                    WHERE tenant_id = ?
+                      AND stripe_price_id = ?
+                      AND active = 1
+                      AND plan_version_id <> ?
+                    LIMIT 1
+                `).get(tenantId, stripePriceId, planVersionId);
+                if (conflictingMapping?.plan_version_id) {
+                    res.writeHead(409, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        error: `Stripe price ${stripePriceId} is already mapped to ${String(conflictingMapping.plan_version_id)}.`,
+                        code: 'BILLING_PRICE_ALREADY_ASSIGNED'
+                    }));
+                    return;
+                }
                 unitAmount = typeof stripePrice.unit_amount === 'number' ? stripePrice.unit_amount : null;
                 currency = stripePrice.currency || null;
             }
@@ -1769,8 +1861,8 @@ export function registerBillingRoutes(deps) {
             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());
+            let currentPlanVersionId = String(currentEntitlement?.plan_version_id || '').trim();
+            let currentInterval = parseInterval(String(currentBilling?.billing_interval || '').trim());
             const stripeAccountDiscovery = await discoverStripeAccountStateForUser(core, {
                 userId,
                 normalizedEmail: normalizedUserEmail,
@@ -1786,8 +1878,13 @@ export function registerBillingRoutes(deps) {
                 return;
             }
             let resolvedCustomerId = currentCustomerId || String(stripeAccountDiscovery.preferredCustomerId || '').trim();
-            if (!currentSubscriptionId && stripeAccountDiscovery.activeSubscriptions.length === 1) {
-                const activeSubscription = stripeAccountDiscovery.activeSubscriptions[0];
+            const activeSubscription = stripeAccountDiscovery.activeSubscriptions.length === 1
+                ? stripeAccountDiscovery.activeSubscriptions[0]
+                : null;
+            let discoveredPlanVersionId = null;
+            let discoveredInterval = null;
+            let discoveredStripePriceId = null;
+            if (!currentSubscriptionId && activeSubscription) {
                 currentSubscriptionId = String(activeSubscription.subscription?.id || '').trim();
                 resolvedCustomerId = String(activeSubscription.customerId || '').trim() || resolvedCustomerId;
                 if (currentSubscriptionId || resolvedCustomerId) {
@@ -1804,7 +1901,28 @@ export function registerBillingRoutes(deps) {
                     stripeCustomerId: resolvedCustomerId
                 });
             }
-            if (currentSubscriptionId && currentPlanVersionId === planVersionId && currentInterval === interval) {
+            if (activeSubscription) {
+                const activeSubscriptionPriceId = String(activeSubscription.subscription?.items?.data?.[0]?.price?.id || '').trim();
+                discoveredStripePriceId = activeSubscriptionPriceId || null;
+                const activePlanVersionId = resolvePlanVersionIdForBillingEvent(core, [
+                    activeSubscription.subscription?.metadata?.planVersionId,
+                    activeSubscription.subscription?.metadata?.plan_version_id
+                ], activeSubscriptionPriceId).planVersionId;
+                discoveredPlanVersionId = activePlanVersionId;
+                discoveredInterval = parseInterval(activeSubscription.subscription?.items?.data?.[0]?.price?.recurring?.interval || '');
+                if (!currentPlanVersionId && activePlanVersionId) {
+                    currentPlanVersionId = activePlanVersionId;
+                }
+                if (!currentInterval) {
+                    currentInterval = discoveredInterval;
+                }
+            }
+            const isCurrentRequestedPlan = (currentPlanVersionId === planVersionId && currentInterval === interval) || (Boolean(currentSubscriptionId)
+                && discoveredPlanVersionId === planVersionId
+                && discoveredInterval === interval) || (Boolean(currentSubscriptionId)
+                && discoveredStripePriceId === priceId
+                && discoveredInterval === interval);
+            if (currentSubscriptionId && isCurrentRequestedPlan) {
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({
                     checkoutState: 'already_current_plan',
@@ -1816,6 +1934,17 @@ export function registerBillingRoutes(deps) {
             if (currentSubscriptionId) {
                 const current = await stripe.subscriptions.retrieve(currentSubscriptionId);
                 const itemId = current.items.data[0]?.id;
+                const currentStripePriceId = String(current.items.data[0]?.price?.id || '').trim();
+                const currentSubscriptionInterval = parseInterval(current.items.data[0]?.price?.recurring?.interval || '');
+                if (currentStripePriceId === priceId && currentSubscriptionInterval === 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 (!itemId) {
                     res.writeHead(400, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'Subscription has no updatable line item.' }));
@@ -1840,7 +1969,7 @@ export function registerBillingRoutes(deps) {
                 res.end(JSON.stringify({
                     checkoutState: 'updated',
                     planVersionId,
-                    message: 'Your subscription was updated successfully.'
+                    message: 'Your subscription update was submitted. Changes will appear after Stripe confirms the update.'
                 }));
                 return;
             }
@@ -1857,10 +1986,17 @@ export function registerBillingRoutes(deps) {
                 planVersionId,
                 interval
             });
+            const successParams = new URLSearchParams({
+                screen: 'plans',
+                checkout: 'success',
+                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}`,
+                success_url: `${baseUrl}/?${successParams.toString()}&session_id={CHECKOUT_SESSION_ID}`,
                 cancel_url: `${baseUrl}/?${cancelParams.toString()}`,
                 ...(resolvedCustomerId
                     ? { customer: resolvedCustomerId }
@@ -1979,7 +2115,10 @@ export function registerBillingRoutes(deps) {
             }
             if (resolvedUserId !== expectedUserId) {
                 res.writeHead(403, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'Checkout session does not belong to the current account.' }));
+                res.end(JSON.stringify({
+                    error: 'Checkout session does not belong to the current account.',
+                    code: 'CHECKOUT_SESSION_ACCOUNT_MISMATCH'
+                }));
                 return;
             }
             let resolvedPlanVersionId = null;
@@ -1999,7 +2138,8 @@ export function registerBillingRoutes(deps) {
                     userId: resolvedUserId,
                     planVersionId: resolvedPlanVersionId,
                     sessionId,
-                    subscriptionId
+                    subscriptionId,
+                    source: 'checkout-confirm'
                 });
                 if (lifecycleGuard.blocked) {
                     res.writeHead(409, { 'Content-Type': 'application/json' });
@@ -2010,20 +2150,54 @@ export function registerBillingRoutes(deps) {
                     return;
                 }
             }
-            core.createUserBillingRecord(resolvedUserId);
-            upsertBillingMirror(core, {
+            if (!subscriptionId || !subscription) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout session is still finalizing your subscription.',
+                    code: 'CHECKOUT_SESSION_INCOMPLETE'
+                }));
+                return;
+            }
+            if (!resolvedPlanVersionId) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout completed, but the purchased plan could not be resolved yet.',
+                    code: 'CHECKOUT_PLAN_VERSION_UNRESOLVED'
+                }));
+                return;
+            }
+            const snapshot = applySubscriptionSnapshot(core, {
                 userId: resolvedUserId,
-                stripeCustomerId: customerId || null,
-                stripeSubscriptionId: subscriptionId || null
+                subscription,
+                source: 'checkout-confirm'
             });
-            if (subscription) {
-                resolvedPlanVersionId = applySubscriptionSnapshot(core, {
-                    userId: resolvedUserId,
-                    subscription,
-                    source: 'checkout-confirm'
-                }).planVersionId;
-                updateCheckoutAttemptStatus(core, sessionId, 'confirmed');
+            resolvedPlanVersionId = snapshot.planVersionId;
+            if (!resolvedPlanVersionId) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout completed, but the purchased plan could not be resolved yet.',
+                    code: 'CHECKOUT_PLAN_VERSION_UNRESOLVED'
+                }));
+                return;
+            }
+            const updatedEntitlement = getEntitlementRow(core, resolvedUserId);
+            const updatedPlanVersionId = String(updatedEntitlement?.plan_version_id || '').trim();
+            const updatedState = String(updatedEntitlement?.entitlement_state || '').trim().toLowerCase();
+            const canonicalSettled = snapshot.canonicalState !== 'checkout_pending'
+                && updatedPlanVersionId === resolvedPlanVersionId
+                && updatedState === snapshot.canonicalState;
+            if (!canonicalSettled) {
+                console.warn(`[Taskforce Billing] Checkout confirmation still settling for user=${resolvedUserId} session=${sessionId} subscription=${subscriptionId || '(missing)'} `
+                    + `planVersionId=${resolvedPlanVersionId} canonicalState=${snapshot.canonicalState} persistedPlanVersionId=${updatedPlanVersionId || '(missing)'} `
+                    + `persistedState=${updatedState || '(missing)'}`);
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout session is still finalizing your plan.',
+                    code: 'CHECKOUT_SESSION_INCOMPLETE'
+                }));
+                return;
             }
+            updateCheckoutAttemptStatus(core, sessionId, 'confirmed');
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
                 success: true,
@@ -2088,7 +2262,7 @@ export function registerBillingRoutes(deps) {
             const baseUrl = resolveBaseUrl(req);
             const session = await stripe.billingPortal.sessions.create({
                 customer: customerId,
-                return_url: `${baseUrl}/settings`
+                return_url: `${baseUrl}/?screen=plans`
             });
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ url: session.url, returnBaseUrl: baseUrl }));
@@ -2249,7 +2423,8 @@ export function registerBillingRoutes(deps) {
                     const lifecycleGuard = resolveCheckoutLifecycleGuard(core, {
                         userId,
                         planVersionId,
-                        subscriptionId: String(subscription.id || '').trim()
+                        subscriptionId: String(subscription.id || '').trim(),
+                        source: 'stripe-webhook'
                     });
                     if (lifecycleGuard.blocked) {
                         recordWebhookFailure(core, {
@@ -2294,7 +2469,8 @@ export function registerBillingRoutes(deps) {
                     const lifecycleGuard = resolveCheckoutLifecycleGuard(core, {
                         userId,
                         planVersionId,
-                        subscriptionId
+                        subscriptionId,
+                        source: 'stripe-webhook'
                     });
                     if (lifecycleGuard.blocked) {
                         recordWebhookFailure(core, {
@@ -2376,6 +2552,15 @@ export function registerBillingRoutes(deps) {
         try {
             const db = core.getDatabaseAdapter();
             const tenantId = core.getTenantId();
+            const environment = requestPricingEnvironment(req);
+            const cacheKey = `${tenantId}:${environment}`;
+            const cacheVersion = buildPublicPricingCacheVersion(core);
+            const cached = publicPricingCache.get(cacheKey);
+            if (cached && cached.version === cacheVersion && cached.expiresAt > Date.now()) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(cached.payload));
+                return;
+            }
             // Get all active plans
             const activePlans = core.listPlanCatalog().filter(p => p.status === 'active');
             // Get all active price mappings with their amounts
@@ -2384,6 +2569,17 @@ export function registerBillingRoutes(deps) {
                 FROM billing_price_mappings
                 WHERE tenant_id = ? AND active = 1
             `).all(tenantId);
+            const pricingByVersionAndInterval = new Map();
+            for (const price of activePrices) {
+                const planVersionId = String(price.plan_version_id || '').trim();
+                const interval = parseInterval(price.billing_interval);
+                if (!planVersionId || !interval)
+                    continue;
+                pricingByVersionAndInterval.set(`${planVersionId}:${interval}`, price);
+            }
+            const featureCatalog = core.listPlanFeatureCatalog();
+            const featureCatalogByKey = new Map(featureCatalog.map((feature) => [feature.featureKey, feature]));
+            const featureCatalogIndexByKey = new Map(featureCatalog.map((feature, index) => [feature.featureKey, index]));
             const plansPayload = activePlans.map((plan) => {
                 const versions = core.listPlanVersions(plan.planId);
                 // Prefer default, else fallback to highest version number
@@ -2391,11 +2587,12 @@ export function registerBillingRoutes(deps) {
                 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');
+                const monthPrice = pricingByVersionAndInterval.get(`${defaultVersion.planVersionId}:month`);
+                const yearPrice = pricingByVersionAndInterval.get(`${defaultVersion.planVersionId}:year`);
                 return {
                     planId: plan.planId,
                     displayName: plan.displayName,
+                    description: plan.description ?? null,
                     status: plan.status,
                     defaultVersion: {
                         planVersionId: defaultVersion.planVersionId,
@@ -2404,9 +2601,48 @@ export function registerBillingRoutes(deps) {
                         trialDays: defaultVersion.trialDays,
                         metadata: defaultVersion.metadata
                     },
-                    features: Object.values(defaultVersion.features || {}).filter((feature) => {
+                    features: Object.values(defaultVersion.features || {})
+                        .reduce((acc, feature) => {
                         const access = String(feature?.access || '').trim().toLowerCase();
-                        return access !== 'disabled';
+                        if (access === 'disabled') {
+                            return acc;
+                        }
+                        const featureKey = String(feature?.featureKey || '').trim();
+                        if (!featureKey || INTERNAL_PUBLIC_PRICING_FEATURE_KEYS.has(featureKey)) {
+                            return acc;
+                        }
+                        const catalogEntry = featureCatalogByKey.get(featureKey);
+                        acc.push({
+                            featureKey,
+                            access,
+                            config: feature?.config && typeof feature.config === 'object'
+                                ? feature.config
+                                : {},
+                            label: catalogEntry?.label ?? null,
+                            description: catalogEntry?.description ?? null,
+                            publicLabel: catalogEntry?.publicLabel ?? null,
+                            publicDescription: catalogEntry?.publicDescription ?? null
+                        });
+                        return acc;
+                    }, [])
+                        .sort((a, b) => {
+                        const orderA = featureCatalogByKey.get(a.featureKey)?.publicDisplayOrder;
+                        const orderB = featureCatalogByKey.get(b.featureKey)?.publicDisplayOrder;
+                        const normalizedOrderA = typeof orderA === 'number' && Number.isFinite(orderA)
+                            ? orderA
+                            : Number.MAX_SAFE_INTEGER;
+                        const normalizedOrderB = typeof orderB === 'number' && Number.isFinite(orderB)
+                            ? orderB
+                            : Number.MAX_SAFE_INTEGER;
+                        if (normalizedOrderA !== normalizedOrderB) {
+                            return normalizedOrderA - normalizedOrderB;
+                        }
+                        const catalogIndexA = featureCatalogIndexByKey.get(a.featureKey) ?? Number.MAX_SAFE_INTEGER;
+                        const catalogIndexB = featureCatalogIndexByKey.get(b.featureKey) ?? Number.MAX_SAFE_INTEGER;
+                        if (catalogIndexA !== catalogIndexB) {
+                            return catalogIndexA - catalogIndexB;
+                        }
+                        return a.featureKey.localeCompare(b.featureKey);
                     }),
                     pricing: {
                         month: monthPrice ? {
@@ -2426,15 +2662,21 @@ export function registerBillingRoutes(deps) {
                     }
                 };
             }).filter(Boolean);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
+            const payload = {
                 asOf: new Date().toISOString(),
                 pricingSource: {
-                    environment: requestPricingEnvironment(req),
+                    environment,
                     runtimeMode: 'cloud'
                 },
                 plans: plansPayload
-            }));
+            };
+            publicPricingCache.set(cacheKey, {
+                payload,
+                version: cacheVersion,
+                expiresAt: Date.now() + PUBLIC_PRICING_CACHE_TTL_MS
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(payload));
         }
         catch (error) {
             const statusCode = resolveErrorStatusCode(error, 500);