handle failure case where lighthouse cannot be reached

Author: brendan-kellam

packages/shared/src/entitlements.test.ts

@@ -63,7 +63,7 @@ const makeLicense = (overrides: Partial<License> = {}): License => ({
     nextRenewalAt: null,
     nextRenewalAmount: null,
     cancelAt: null,
-    lastSyncAt: null,
+    lastSyncAt: new Date(),
     createdAt: new Date(),
     updatedAt: new Date(),
     ...overrides,
@@ -172,6 +172,47 @@ describe('getEntitlements', () => {
         mocks.env.SOURCEBOT_EE_LICENSE_KEY = 'sourcebot_ee_not-a-valid-payload';
         expect(getEntitlements(null)).toEqual([]);
     });
+
+    describe('online license staleness', () => {
+        const STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
+
+        test('returns entitlements when lastSyncAt is recent', () => {
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['sso'],
+                lastSyncAt: new Date(Date.now() - 24 * 60 * 60 * 1000), // 1 day ago
+            });
+            expect(getEntitlements(license)).toEqual(['sso']);
+        });
+
+        test('returns empty when lastSyncAt is past the stale threshold', () => {
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['sso'],
+                lastSyncAt: new Date(Date.now() - STALE_THRESHOLD_MS - 60 * 1000), // 7d + 1min
+            });
+            expect(getEntitlements(license)).toEqual([]);
+        });
+
+        test('returns empty when lastSyncAt is null', () => {
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['sso'],
+                lastSyncAt: null,
+            });
+            expect(getEntitlements(license)).toEqual([]);
+        });
+
+        test('returns entitlements at the threshold boundary', () => {
+            // Exactly at the threshold should still be treated as valid (<=).
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['sso'],
+                lastSyncAt: new Date(Date.now() - STALE_THRESHOLD_MS + 1000),
+            });
+            expect(getEntitlements(license)).toEqual(['sso']);
+        });
+    });
 });
 
 describe('hasEntitlement', () => {

packages/shared/src/entitlements.ts

@@ -88,11 +88,26 @@ const getValidOfflineLicense = (): getValidOfflineLicense | null => {
     return payload;
 }
 
+// If the license hasn't successfully synced with Lighthouse for this long,                                                                                                                                                            
+// the locally-cached state is no longer trusted. This guards against an                                                                                                                                                             
+// operator blocking egress to prevent the license row from hearing about                                                                                                                                                            
+// a canceled or past-due subscription. 7 days absorbs week-long transient                                                                                                                                                             
+// outages (weekends, firewall rollouts) without punishing legitimate                                                                                                                                                                  
+// customers.                                                                                                                                                                                                                          
+export const STALE_ONLINE_LICENSE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Surface a UI warning (banner + "refreshed" timestamp color) when the
+// license hasn't synced for this long. Must be < the enforcement threshold
+// so the warning has a chance to fire before entitlements are stripped.
+export const STALE_ONLINE_LICENSE_WARNING_THRESHOLD_MS = 48 * 60 * 60 * 1000;
+
 const getValidOnlineLicense = (_license: License | null): License | null => {
     if (
         _license &&
         _license.status &&
-        ACTIVE_ONLINE_LICENSE_STATUSES.includes(_license.status as LicenseStatus)
+        ACTIVE_ONLINE_LICENSE_STATUSES.includes(_license.status as LicenseStatus) &&
+        _license.lastSyncAt &&
+        (Date.now() - _license.lastSyncAt.getTime()) <= STALE_ONLINE_LICENSE_THRESHOLD_MS
     ) {
         return _license;
     }

packages/shared/src/index.server.ts

@@ -7,6 +7,8 @@ export {
     isAnonymousAccessAvailable as _isAnonymousAccessAvailable,
     getSeatCap,
     getOfflineLicenseMetadata,
+    STALE_ONLINE_LICENSE_THRESHOLD_MS,
+    STALE_ONLINE_LICENSE_WARNING_THRESHOLD_MS,
 } from "./entitlements.js";
 export type {
     Entitlement,

packages/web/src/app/(app)/components/banners/bannerResolver.test.ts

@@ -5,10 +5,19 @@ import type { OfflineLicenseMetadata } from '@sourcebot/shared';
 // Stub the rendered banner components — these tests assert on descriptor
 // metadata only (id, priority, etc), so avoiding their React/Next.js import
 // chains keeps the suite focused on resolver logic.
+// Stub @sourcebot/shared: importing its real index initializes env-backed
+// server code that can't run in the test environment. The resolver only
+// needs the threshold constant; type imports are erased at runtime.
+vi.mock('@sourcebot/shared', () => ({
+    STALE_ONLINE_LICENSE_THRESHOLD_MS: 7 * 24 * 60 * 60 * 1000,
+    STALE_ONLINE_LICENSE_WARNING_THRESHOLD_MS: 48 * 60 * 60 * 1000,
+}));
+
 vi.mock('./permissionSyncBanner', () => ({ PermissionSyncBanner: () => null }));
 vi.mock('./licenseExpiredBanner', () => ({ LicenseExpiredBanner: () => null }));
 vi.mock('./licenseExpiryHeadsUpBanner', () => ({ LicenseExpiryHeadsUpBanner: () => null }));
 vi.mock('./invoicePastDueBanner', () => ({ InvoicePastDueBanner: () => null }));
+vi.mock('./servicePingFailedBanner', () => ({ ServicePingFailedBanner: () => null }));
 
 import { resolveActiveBanner, type BannerContext } from './bannerResolver';
 
@@ -34,7 +43,7 @@ const makeLicense = (overrides: Partial<License> = {}): License => ({
     nextRenewalAt: null,
     nextRenewalAmount: null,
     cancelAt: null,
-    lastSyncAt: null,
+    lastSyncAt: NOW,
     createdAt: NOW,
     updatedAt: NOW,
     ...overrides,
@@ -305,6 +314,136 @@ describe('resolveActiveBanner', () => {
         });
     });
 
+    describe('service ping staleness', () => {
+        const WARNING_MS = 48 * 60 * 60 * 1000;
+        const ENFORCEMENT_MS = 7 * 24 * 60 * 60 * 1000;
+        const msBefore = (ms: number) => new Date(NOW.getTime() - ms);
+
+        test('fresh lastSyncAt → no banner', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({ status: 'active', lastSyncAt: msBefore(1000) }),
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('stale between 48h and 7d → warning (dismissible, owner)', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'active',
+                    lastSyncAt: msBefore(WARNING_MS + 60_000),
+                }),
+            }));
+            expect(result?.id).toBe('servicePingFailed');
+            expect(result?.dismissible).toBe(true);
+            expect(result?.audience).toBe('owner');
+        });
+
+        test('stale beyond 7d → enforced (non-dismissible, everyone)', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'active',
+                    lastSyncAt: msBefore(ENFORCEMENT_MS + 60_000),
+                }),
+            }));
+            expect(result?.id).toBe('servicePingFailed');
+            expect(result?.dismissible).toBe(false);
+            expect(result?.audience).toBe('everyone');
+        });
+
+        test('null lastSyncAt on existing license → enforced', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({ status: 'active', lastSyncAt: null }),
+            }));
+            expect(result?.id).toBe('servicePingFailed');
+            expect(result?.audience).toBe('everyone');
+        });
+
+        test('offline license suppresses staleness banner', () => {
+            const result = resolveActiveBanner(makeContext({
+                offlineLicense: makeOfflineLicense(),
+                license: makeLicense({ status: 'active', lastSyncAt: null }),
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('warning banner hidden from non-owners', () => {
+            const result = resolveActiveBanner(makeContext({
+                role: OrgRole.MEMBER,
+                license: makeLicense({
+                    status: 'active',
+                    lastSyncAt: msBefore(WARNING_MS + 60_000),
+                }),
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('enforced banner shown to non-owners', () => {
+            const result = resolveActiveBanner(makeContext({
+                role: OrgRole.MEMBER,
+                license: makeLicense({
+                    status: 'active',
+                    lastSyncAt: msBefore(ENFORCEMENT_MS + 60_000),
+                }),
+            }));
+            expect(result?.id).toBe('servicePingFailed');
+        });
+
+        test('warning: dismissed today → filtered out', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'active',
+                    lastSyncAt: msBefore(WARNING_MS + 60_000),
+                }),
+                dismissals: { servicePingFailed: TODAY },
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('enforced: dismissal cookie is ignored', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'active',
+                    lastSyncAt: msBefore(ENFORCEMENT_MS + 60_000),
+                }),
+                dismissals: { servicePingFailed: TODAY },
+            }));
+            expect(result?.id).toBe('servicePingFailed');
+        });
+
+        test('enforced outranks invoice past due', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'past_due',
+                    lastSyncAt: msBefore(ENFORCEMENT_MS + 60_000),
+                }),
+            }));
+            expect(result?.id).toBe('servicePingFailed');
+            expect(result?.audience).toBe('everyone');
+        });
+
+        test('license expired outranks enforced ping staleness', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'canceled',
+                    lastSyncAt: msBefore(ENFORCEMENT_MS + 60_000),
+                }),
+            }));
+            expect(result?.id).toBe('licenseExpired');
+        });
+
+        test('warning ranks below permission sync', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'active',
+                    lastSyncAt: msBefore(WARNING_MS + 60_000),
+                }),
+                hasPermissionSyncEntitlement: true,
+                hasPendingFirstSync: true,
+            }));
+            expect(result?.id).toBe('permissionSync');
+        });
+    });
+
     describe('permission sync', () => {
         test('entitlement + pending → permissionSync', () => {
             const result = resolveActiveBanner(makeContext({

packages/web/src/app/(app)/components/banners/bannerResolver.tsx

@@ -1,10 +1,16 @@
 import { OrgRole, type License } from "@sourcebot/db";
-import type { LicenseStatus, OfflineLicenseMetadata } from "@sourcebot/shared";
+import {
+    STALE_ONLINE_LICENSE_THRESHOLD_MS,
+    STALE_ONLINE_LICENSE_WARNING_THRESHOLD_MS,
+    type LicenseStatus,
+    type OfflineLicenseMetadata,
+} from "@sourcebot/shared";
 import { BannerPriority, type BannerDescriptor, type BannerId } from "./types";
 import { PermissionSyncBanner } from "./permissionSyncBanner";
 import { LicenseExpiredBanner } from "./licenseExpiredBanner";
 import { LicenseExpiryHeadsUpBanner } from "./licenseExpiryHeadsUpBanner";
 import { InvoicePastDueBanner } from "./invoicePastDueBanner";
+import { ServicePingFailedBanner } from "./servicePingFailedBanner";
 
 const EXPIRY_HEADS_UP_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
 
@@ -69,6 +75,39 @@ function buildCandidates(ctx: BannerContext): BannerDescriptor[] {
         });
     }
 
+    const pingStaleness = getPingStaleness(ctx);
+    if (pingStaleness === 'warning') {
+        const lastSyncAtIso = ctx.license?.lastSyncAt?.toISOString() ?? null;
+        banners.push({
+            id: 'servicePingFailed',
+            priority: BannerPriority.SERVICE_PING_FAILED,
+            dismissible: true,
+            audience: 'owner',
+            render: (props) => (
+                <ServicePingFailedBanner
+                    {...props}
+                    variant="warning"
+                    lastSyncAt={lastSyncAtIso}
+                />
+            ),
+        });
+    } else if (pingStaleness === 'enforced') {
+        const lastSyncAtIso = ctx.license?.lastSyncAt?.toISOString() ?? null;
+        banners.push({
+            id: 'servicePingFailed',
+            priority: BannerPriority.SERVICE_PING_ENFORCED,
+            dismissible: false,
+            audience: 'everyone',
+            render: (props) => (
+                <ServicePingFailedBanner
+                    {...props}
+                    variant="enforced"
+                    lastSyncAt={lastSyncAtIso}
+                />
+            ),
+        });
+    }
+
     if (ctx.hasPermissionSyncEntitlement && ctx.hasPendingFirstSync) {
         banners.push({
             id: 'permissionSync',
@@ -129,3 +168,24 @@ function getLicenseExpiryState(ctx: BannerContext): LicenseExpiryState {
     }
     return null;
 }
+
+// 'enforced' once entitlements.ts would strip entitlements; 'warning' in the
+// lead-up. Offline licenses don't ping, so they're never stale here.
+function getPingStaleness(ctx: BannerContext): 'warning' | 'enforced' | null {
+    if (ctx.offlineLicense || !ctx.license) {
+        return null;
+    }
+    // Matches the fail-safe in entitlements.ts: a license row without a
+    // lastSyncAt means the first verification never succeeded.
+    if (!ctx.license.lastSyncAt) {
+        return 'enforced';
+    }
+    const stalenessMs = ctx.now.getTime() - ctx.license.lastSyncAt.getTime();
+    if (stalenessMs > STALE_ONLINE_LICENSE_THRESHOLD_MS) {
+        return 'enforced';
+    }
+    if (stalenessMs > STALE_ONLINE_LICENSE_WARNING_THRESHOLD_MS) {
+        return 'warning';
+    }
+    return null;
+}

packages/web/src/app/(app)/components/banners/licenseExpiredBanner.tsx

@@ -9,7 +9,7 @@ interface LicenseExpiredBannerProps extends BannerProps {
     source: 'offline' | 'online';
 }
 
-// @todo: This should instead be a docs page that explains the enterprise offering.
+// @nocheckin: This should instead be a docs page that explains the enterprise offering.
 const ENTERPRISE_OFFERING_DOCS_LINK = "https://sourcebot.dev/pricing";
 
 export function LicenseExpiredBanner({ id, dismissible, role, source }: LicenseExpiredBannerProps) {
@@ -37,7 +37,7 @@ export function LicenseExpiredBanner({ id, dismissible, role, source }: LicenseE
             id={id}
             dismissible={dismissible}
             icon={<AlertTriangle className="h-4 w-4 mt-0.5 text-destructive" />}
-            title="License Expired"
+            title="License expired"
             description={description}
             action={isOwner ? (
                 <Button asChild size="sm" variant="outline">