fix: verify signed online license entitlements

Author: brendan-kellam

packages/db/prisma/migrations/20260713000000_add_license_assertion/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "License" ADD COLUMN "licenseAssertion" TEXT;

packages/db/prisma/schema.prisma

@@ -375,6 +375,9 @@ model License {
 
   lastSyncAt        DateTime?
   lastSyncErrorCode String?
+  /// Compact, signed online-license assertion returned by Lighthouse.
+  /// Authorization must be derived from this assertion when it is present.
+  licenseAssertion  String?
   createdAt         DateTime @default(now())
   updatedAt         DateTime @updatedAt
 }

packages/shared/src/entitlements.test.ts

@@ -5,6 +5,7 @@ const mocks = vi.hoisted(() => ({
     env: {
         SOURCEBOT_PUBLIC_KEY_PATH: '/tmp/test-key',
         SOURCEBOT_EE_LICENSE_KEY: undefined as string | undefined,
+        SOURCEBOT_INSTALL_ID: 'test-install',
     } as Record<string, string | undefined>,
     verifySignature: vi.fn(() => true),
 }));
@@ -78,11 +79,29 @@ const makeLicense = (overrides: Partial<License> = {}): License => ({
     yearlyPeakSeats: null,
     lastSyncAt: new Date(),
     lastSyncErrorCode: null,
+    licenseAssertion: null,
     createdAt: new Date(),
     updatedAt: new Date(),
     ...overrides,
 });
 
+const onlineAssertion = (overrides: Record<string, unknown> = {}): string => {
+    const payload = {
+        version: 1,
+        audience: 'sourcebot-online-license',
+        licenseId: 'subscription-1',
+        installId: 'test-install',
+        status: 'active',
+        entitlements: ['sso'],
+        seats: 10,
+        issuedAt: new Date(Date.now() - 60 * 1000).toISOString(),
+        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+        ...overrides,
+    };
+
+    return `${Buffer.from(JSON.stringify(payload)).toString('base64url')}.fake-signature`;
+};
+
 beforeEach(() => {
     mocks.env.SOURCEBOT_EE_LICENSE_KEY = undefined;
     mocks.verifySignature.mockReturnValue(true);
@@ -178,6 +197,63 @@ describe('getEntitlements', () => {
         expect(getEntitlements(makeLicense({ entitlements: ['sso'] }))).toEqual([]);
     });
 
+    describe('signed online assertions', () => {
+        test('uses entitlements from a valid assertion instead of mutable columns', () => {
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['audit'],
+                licenseAssertion: onlineAssertion({ entitlements: ['sso'] }),
+            });
+
+            expect(getEntitlements(license)).toEqual(['sso']);
+        });
+
+        test('does not fall back to mutable columns when the signature is invalid', () => {
+            mocks.verifySignature.mockReturnValue(false);
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['audit'],
+                licenseAssertion: onlineAssertion(),
+            });
+
+            expect(getEntitlements(license)).toEqual([]);
+        });
+
+        test('rejects an assertion issued for another installation', () => {
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['audit'],
+                licenseAssertion: onlineAssertion({ installId: 'different-install' }),
+            });
+
+            expect(getEntitlements(license)).toEqual([]);
+        });
+
+        test('rejects an expired assertion even when lastSyncAt was forged', () => {
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['audit'],
+                lastSyncAt: new Date(),
+                licenseAssertion: onlineAssertion({
+                    issuedAt: new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString(),
+                    expiresAt: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+                }),
+            });
+
+            expect(getEntitlements(license)).toEqual([]);
+        });
+
+        test('rejects active mutable columns when the signed status is canceled', () => {
+            const license = makeLicense({
+                status: 'active',
+                entitlements: ['audit'],
+                licenseAssertion: onlineAssertion({ status: 'canceled' }),
+            });
+
+            expect(getEntitlements(license)).toEqual([]);
+        });
+    });
+
     test('returns all entitlements when offline key is valid', () => {
         mocks.env.SOURCEBOT_EE_LICENSE_KEY = validOfflineKey({ seats: 50 });
         const result = getEntitlements(null);

packages/shared/src/entitlements.ts

@@ -27,6 +27,14 @@ const ACTIVE_ONLINE_LICENSE_STATUSES: LicenseStatus[] = [
     'past_due',
 ];
 
+const ONLINE_LICENSE_ASSERTION_AUDIENCE = 'sourcebot-online-license';
+const ONLINE_LICENSE_ASSERTION_CLOCK_SKEW_MS = 5 * 60 * 1000;
+
+// Compatibility switch for the first release that understands signed online
+// licenses. Set this to false in the enforcement release, after Lighthouse has
+// been returning assertions for at least one full online-license TTL.
+const ALLOW_LEGACY_UNSIGNED_ONLINE_LICENSES = true;
+
 // @WARNING: when adding a new entitlement to this list, make sure
 // lighthouse/lambda/entitlements.ts is also updated && deployed
 // prior to rolling a new Sourcebot version.
@@ -47,6 +55,74 @@ const ALL_ENTITLEMENTS = [
 ] as const;
 export type Entitlement = (typeof ALL_ENTITLEMENTS)[number];
 
+const onlineLicenseAssertionPayloadSchema = z.object({
+    version: z.literal(1),
+    audience: z.literal(ONLINE_LICENSE_ASSERTION_AUDIENCE),
+    licenseId: z.string().min(1),
+    installId: z.string().min(1),
+    status: z.enum([
+        'active',
+        'trialing',
+        'past_due',
+        'unpaid',
+        'canceled',
+        'incomplete',
+        'incomplete_expired',
+        'paused',
+    ]),
+    entitlements: z.array(z.enum(ALL_ENTITLEMENTS)),
+    seats: z.number().int().nonnegative(),
+    issuedAt: z.string().datetime(),
+    expiresAt: z.string().datetime(),
+}).strict();
+
+export type OnlineLicenseAssertionPayload = z.infer<typeof onlineLicenseAssertionPayloadSchema>;
+
+/**
+ * Verifies and decodes an online-license assertion. The signature covers the
+ * encoded payload itself, avoiding cross-language JSON canonicalization.
+ */
+export const verifyOnlineLicenseAssertion = (assertion: string): OnlineLicenseAssertionPayload | null => {
+    try {
+        const parts = assertion.split('.');
+        if (parts.length !== 2) {
+            return null;
+        }
+
+        const [encodedPayload, signature] = parts;
+        if (!encodedPayload || !signature) {
+            return null;
+        }
+
+        if (!verifySignature(encodedPayload, signature, env.SOURCEBOT_PUBLIC_KEY_PATH)) {
+            logger.error('Online license assertion signature verification failed');
+            return null;
+        }
+
+        const decodedPayload = Buffer.from(encodedPayload, 'base64url').toString('utf8');
+        const payload = onlineLicenseAssertionPayloadSchema.parse(JSON.parse(decodedPayload));
+        const issuedAt = new Date(payload.issuedAt).getTime();
+        const expiresAt = new Date(payload.expiresAt).getTime();
+        const now = Date.now();
+
+        if (
+            payload.installId !== env.SOURCEBOT_INSTALL_ID ||
+            issuedAt > now + ONLINE_LICENSE_ASSERTION_CLOCK_SKEW_MS ||
+            expiresAt <= now ||
+            expiresAt <= issuedAt ||
+            (expiresAt - issuedAt) > STALE_ONLINE_LICENSE_THRESHOLD_MS
+        ) {
+            logger.error('Online license assertion claims are invalid');
+            return null;
+        }
+
+        return payload;
+    } catch (error) {
+        logger.error(`Failed to verify online license assertion: ${error}`);
+        return null;
+    }
+};
+
 const decodeOfflineLicenseKeyPayload = (payload: string): getValidOfflineLicense | null => {
     try {
         const decodedPayload = base64Decode(payload);
@@ -114,7 +190,9 @@ export const STALE_ONLINE_LICENSE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
 // 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 => {
+type ValidOnlineLicense = Pick<OnlineLicenseAssertionPayload, 'entitlements' | 'status'>;
+
+const getValidLegacyOnlineLicense = (_license: License | null): ValidOnlineLicense | null => {
     if (
         _license &&
         _license.status &&
@@ -123,7 +201,32 @@ const getValidOnlineLicense = (_license: License | null): License | null => {
         (Date.now() - _license.lastSyncAt.getTime()) <= STALE_ONLINE_LICENSE_THRESHOLD_MS &&
         _license.lastSyncErrorCode !== 'ACTIVATION_CODE_BOUND_TO_DIFFERENT_INSTANCE'
     ) {
-        return _license;
+        return {
+            entitlements: _license.entitlements as Entitlement[],
+            status: _license.status as LicenseStatus,
+        };
+    }
+
+    return null;
+}
+
+const getValidOnlineLicense = (_license: License | null): ValidOnlineLicense | null => {
+    // A present but invalid assertion must never fall back to unsigned columns.
+    if (_license?.licenseAssertion !== null && _license?.licenseAssertion !== undefined) {
+        if (_license.lastSyncErrorCode === 'ACTIVATION_CODE_BOUND_TO_DIFFERENT_INSTANCE') {
+            return null;
+        }
+
+        const assertion = verifyOnlineLicenseAssertion(_license.licenseAssertion);
+        if (assertion && ACTIVE_ONLINE_LICENSE_STATUSES.includes(assertion.status)) {
+            return assertion;
+        }
+
+        return null;
+    }
+
+    if (ALLOW_LEGACY_UNSIGNED_ONLINE_LICENSES) {
+        return getValidLegacyOnlineLicense(_license);
     }
 
     return null;
@@ -208,4 +311,4 @@ export const getSeatCap = (): number | undefined => {
     }
 
     return undefined;
-}
+}

packages/shared/src/index.server.ts

@@ -12,10 +12,12 @@ export {
     getOfflineLicenseMetadata,
     STALE_ONLINE_LICENSE_THRESHOLD_MS,
     STALE_ONLINE_LICENSE_WARNING_THRESHOLD_MS,
+    verifyOnlineLicenseAssertion,
 } from "./entitlements.js";
 export type {
     Entitlement,
     OfflineLicenseMetadata,
+    OnlineLicenseAssertionPayload,
 } from "./entitlements.js";
 export type {
     RepoMetadata,

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

@@ -60,6 +60,7 @@ const makeLicense = (overrides: Partial<License> = {}): License => ({
     yearlyPeakSeats: null,
     lastSyncAt: NOW,
     lastSyncErrorCode: null,
+    licenseAssertion: null,
     createdAt: NOW,
     updatedAt: NOW,
     ...overrides,

packages/web/src/features/billing/servicePing.ts

@@ -7,7 +7,8 @@ import {
     decryptActivationCode,
     env,
     SOURCEBOT_VERSION,
-    isValidOfflineLicenseActive
+    isValidOfflineLicenseActive,
+    verifyOnlineLicenseAssertion,
 } from "@sourcebot/shared";
 import { client } from "./client";
 import { ServicePingRequest } from "./types";
@@ -127,6 +128,13 @@ export const syncWithLighthouse = async (orgId: number) => {
 
     // If we have a license and Lighthouse returned license data, sync it
     if (license && response.license) {
+        if (response.licenseAssertion && !verifyOnlineLicenseAssertion(response.licenseAssertion)) {
+            // Never persist an assertion we cannot authenticate. In particular,
+            // do not silently write only the legacy fields and create a
+            // signature-downgrade path.
+            throw new Error('Lighthouse returned an invalid online license assertion');
+        }
+
         const {
             entitlements,
             seats,
@@ -174,6 +182,7 @@ export const syncWithLighthouse = async (orgId: number) => {
                 yearlyPeakSeats: yearlyTermStatus?.peakSeats ?? null,
                 lastSyncAt: new Date(),
                 lastSyncErrorCode: null,
+                ...(response.licenseAssertion && { licenseAssertion: response.licenseAssertion }),
             },
         });
 

packages/web/src/features/billing/types.ts

@@ -102,6 +102,8 @@ export const servicePingResponseSchema = z.object({
         hasPaymentMethod: z.boolean(),
         yearlyTermStatus: yearlyTermStatusSchema.optional(),
     }).optional(),
+    // Optional while older Lighthouse deployments are being upgraded.
+    licenseAssertion: z.string().optional(),
 });
 export type ServicePingResponse = z.infer<typeof servicePingResponseSchema>;