Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(license): clock anchor, limit-only Pro grace, consent under DO_NOT_TRACK

review4a6cc07845e8
diff --git a/src/core/license.test.ts b/src/core/license.test.ts
index 85f09b160..cdd8ed291 100644
--- a/src/core/license.test.ts
+++ b/src/core/license.test.ts
@@ -857,3 +857,253 @@ describe('license detail + release', () => {
expect(d.key).toBe('K')
})
})
+
+describe('license clock anchor + project-limit Pro grace + DO_NOT_TRACK consent', () => {
+ let fetchMock: ReturnType<typeof vi.fn>
+ let fake: import('./platform-fake').FakePlatform
+
+ const DAY = 24 * HOUR
+ const DAY_S = 24 * 60 * 60
+ const file = (): string => path.join(h.userData, 'license.json')
+ function store(s: { token?: string; key?: string; lastSeen?: number }): void {
+ writeFileSync(file(), JSON.stringify(s))
+ }
+ /** A token signed by a key this install does NOT trust — the signature half of verify(). */
+ function forge(ttlSeconds: number): string {
+ const other = crypto.generateKeyPairSync('ed25519').privateKey
+ const payload = Buffer.from(
+ JSON.stringify({
+ deviceId: 'test-device',
+ tier: 'pro',
+ licenseId: 'lic_forged',
+ exp: Math.floor(Date.now() / 1000) + ttlSeconds
+ })
+ ).toString('base64url')
+ return `${payload}.${crypto.sign(null, Buffer.from(payload), other).toString('base64url')}`
+ }
+ const urls = (): string[] => fetchMock.mock.calls.map((c) => String(c[0]))
+
+ beforeEach(async () => {
+ vi.useFakeTimers({ toFake: ['setInterval', 'Date'] })
+ h.userData = mkdtempSync(path.join(tmpdir(), 'nt-license-grace-'))
+ writeFileSync(path.join(h.userData, 'device-id'), 'test-device')
+ delete process.env.DO_NOT_TRACK
+ delete process.env.NODETERM_TELEMETRY_DISABLED
+ process.env.NODETERM_API_BASE = 'http://127.0.0.1:1'
+ // Offline by default: the launch refresh keeps the stored token (offline grace).
+ fetchMock = vi.fn().mockRejectedValue(new Error('offline'))
+ vi.stubGlobal('fetch', fetchMock)
+ vi.resetModules()
+ const { initPlatform } = await import('./platform')
+ const { fakePlatform } = await import('./platform-fake')
+ fake = fakePlatform({ userDataDir: h.userData, isPackaged: false })
+ initPlatform(fake)
+ })
+
+ afterEach(async () => {
+ vi.unstubAllGlobals()
+ vi.useRealTimers()
+ const { resetPlatformForTests } = await import('./platform')
+ resetPlatformForTests()
+ delete process.env.DO_NOT_TRACK
+ delete process.env.NODETERM_TELEMETRY_DISABLED
+ process.env.NODETERM_API_BASE = 'http://127.0.0.1:1'
+ rmSync(h.userData, { recursive: true, force: true })
+ })
+
+ describe('clockAnchorMs', () => {
+ it('is the wall clock when nothing later has been observed', async () => {
+ const { clockAnchorMs } = await import('./license')
+ expect(clockAnchorMs()).toBe(Date.now())
+ store({ lastSeen: Math.floor(Date.now() / 1000) - 5 * DAY_S })
+ expect(clockAnchorMs()).toBe(Date.now())
+ })
+
+ it('is the stored lastSeen when the wall clock is behind it (a rolled-back clock)', async () => {
+ const ahead = Math.floor(Date.now() / 1000) + 40 * DAY_S
+ store({ lastSeen: ahead })
+ const { clockAnchorMs } = await import('./license')
+ expect(clockAnchorMs()).toBe(ahead * 1000)
+ })
+ })
+
+ describe('proForProjectLimit', () => {
+ it('is the 30-day window', async () => {
+ const { PRO_LIMIT_GRACE_MS } = await import('./license')
+ expect(PRO_LIMIT_GRACE_MS).toBe(30 * 24 * 60 * 60 * 1000)
+ })
+
+ it('a live token is Pro for the limit and for everything else', async () => {
+ store({ token: mint(7 * DAY_S) })
+ const { isPremium, proForProjectLimit } = await import('./license')
+ expect(isPremium()).toBe(true)
+ expect(proForProjectLimit()).toBe(true)
+ })
+
+ it('a token that expired 10 days ago is Pro for the limit ONLY', async () => {
+ store({ token: mint(-10 * DAY_S, 'test-device', 5) })
+ const { initLicense, isPremium, licensedSeats, proForProjectLimit } = await import('./license')
+ expect(isPremium()).toBe(false)
+ expect(proForProjectLimit()).toBe(true)
+ // Every other Pro feature still reads the token as expired.
+ expect(licensedSeats()).toBe(0)
+ initLicense()
+ await refreshed()
+ const status = (await fake.handlers[IPC.licenseStatus]()) as LicenseStatus
+ expect(status.active).toBe(false)
+ expect(status.seats).toBe(0)
+ })
+
+ it('a token that expired 31 days ago is not Pro for anything', async () => {
+ store({ token: mint(-31 * DAY_S) })
+ const { isPremium, proForProjectLimit } = await import('./license')
+ expect(isPremium()).toBe(false)
+ expect(proForProjectLimit()).toBe(false)
+ })
+
+ it('measures the 30 days from the clock anchor, not the wall clock', async () => {
+ // 20 days past expiry by the wall clock (inside the window), but this install has already
+ // observed a time 40 days ahead — 60 days past expiry by the anchor. Rolling the clock back
+ // must not buy the window again.
+ store({ token: mint(-20 * DAY_S), lastSeen: Math.floor(Date.now() / 1000) + 40 * DAY_S })
+ const { proForProjectLimit } = await import('./license')
+ expect(proForProjectLimit()).toBe(false)
+ })
+
+ it('a token minted for another device is not Pro for the limit, expired or not', async () => {
+ store({ token: mint(-10 * DAY_S, 'other-device') })
+ const first = await import('./license')
+ expect(first.proForProjectLimit()).toBe(false)
+ store({ token: mint(7 * DAY_S, 'other-device') })
+ expect(first.proForProjectLimit()).toBe(false)
+ })
+
+ it('a token signed by any other key is not Pro for the limit', async () => {
+ store({ token: forge(-10 * DAY_S) })
+ const { proForProjectLimit } = await import('./license')
+ expect(proForProjectLimit()).toBe(false)
+ })
+
+ it('no stored token is not Pro for the limit', async () => {
+ const { proForProjectLimit } = await import('./license')
+ expect(proForProjectLimit()).toBe(false)
+ })
+
+ it('ends with the token a 2xx active:false deletes', async () => {
+ // The device-bound refresh drops the token on the server's "no longer entitled" answer, so a
+ // stored token is itself the proof that no such answer has arrived since (spec §6).
+ store({ token: mint(-10 * DAY_S) })
+ fetchMock.mockResolvedValue(jsonResponse({ active: false }))
+ const { initLicense, proForProjectLimit } = await import('./license')
+ expect(proForProjectLimit()).toBe(true)
+ initLicense()
+ await refreshed()
+ expect(proForProjectLimit()).toBe(false)
+ })
+ })
+
+ describe('isDntEnv', () => {
+ it('reads DO_NOT_TRACK and the telemetry kill switch, live', async () => {
+ const { isDntEnv } = await import('./license')
+ expect(isDntEnv()).toBe(false)
+ process.env.DO_NOT_TRACK = '1'
+ expect(isDntEnv()).toBe(true)
+ delete process.env.DO_NOT_TRACK
+ process.env.NODETERM_TELEMETRY_DISABLED = '1'
+ expect(isDntEnv()).toBe(true)
+ })
+ })
+
+ describe('licenseNetworkGate', () => {
+ it('is ok with no DO_NOT_TRACK, whatever consent says', async () => {
+ const { licenseNetworkGate } = await import('./license')
+ expect(licenseNetworkGate()).toBe('ok')
+ })
+
+ it('is disabled in an unpackaged build without NODETERM_API_BASE, even with DNT consent', async () => {
+ delete process.env.NODETERM_API_BASE
+ const { licenseNetworkGate, setLicenseNetworkConsent } = await import('./license')
+ expect(licenseNetworkGate()).toBe('disabled')
+ process.env.DO_NOT_TRACK = '1'
+ setLicenseNetworkConsent(() => true)
+ expect(licenseNetworkGate()).toBe('disabled')
+ // A packaged build talks to the default API.
+ const { initPlatform } = await import('./platform')
+ const { fakePlatform } = await import('./platform-fake')
+ initPlatform(fakePlatform({ userDataDir: h.userData, isPackaged: true }))
+ expect(licenseNetworkGate()).toBe('ok')
+ })
+
+ it('asks for consent under DO_NOT_TRACK or the kill switch, and reads it on every call', async () => {
+ process.env.DO_NOT_TRACK = '1'
+ const { licenseNetworkGate, setLicenseNetworkConsent } = await import('./license')
+ expect(licenseNetworkGate()).toBe('consent_required') // default: no consent
+ let consented = true
+ setLicenseNetworkConsent(() => consented)
+ expect(licenseNetworkGate()).toBe('ok')
+ consented = false // revoked in Settings → Privacy: takes effect at once
+ expect(licenseNetworkGate()).toBe('consent_required')
+ delete process.env.DO_NOT_TRACK
+ process.env.NODETERM_TELEMETRY_DISABLED = '1'
+ expect(licenseNetworkGate()).toBe('consent_required')
+ })
+
+ it('a consent callback that throws reads as no consent', async () => {
+ process.env.DO_NOT_TRACK = '1'
+ const { licenseNetworkGate, setLicenseNetworkConsent } = await import('./license')
+ setLicenseNetworkConsent(() => {
+ throw new Error('settings not loaded')
+ })
+ expect(licenseNetworkGate()).toBe('consent_required')
+ })
+ })
+
+ describe('license calls under DO_NOT_TRACK', () => {
+ it('without consent, the launch refresh makes no request and keeps the stored token', async () => {
+ process.env.DO_NOT_TRACK = '1'
+ store({ token: mint(7 * DAY_S) })
+ const { initLicense, isPremium } = await import('./license')
+ initLicense()
+ await refreshed()
+ expect(fetchMock).not.toHaveBeenCalled()
+ expect(isPremium()).toBe(true)
+ })
+
+ it('without consent, a key-paste refresh makes no request either', async () => {
+ process.env.NODETERM_TELEMETRY_DISABLED = '1'
+ store({ key: 'KEY-1', token: mint(7 * DAY_S) })
+ const { initLicense } = await import('./license')
+ initLicense()
+ await refreshed()
+ expect(fetchMock).not.toHaveBeenCalled()
+ })
+
+ it('with consent, the device-bound refresh asks /v1/license/status and stores the token', async () => {
+ process.env.DO_NOT_TRACK = '1'
+ const token = mint(7 * DAY_S)
+ fetchMock.mockResolvedValue(jsonResponse({ active: true, token }))
+ const { initLicense, isPremium, setLicenseNetworkConsent } = await import('./license')
+ setLicenseNetworkConsent(() => true)
+ initLicense()
+ await refreshed()
+ expect(urls()).toEqual([
+ 'http://127.0.0.1:1/v1/license/status?deviceId=test-device'
+ ])
+ expect(isPremium()).toBe(true)
+ })
+
+ it('with consent, the detail route runs too', async () => {
+ process.env.DO_NOT_TRACK = '1'
+ store({ token: mint(7 * DAY_S) })
+ const { initLicense, setLicenseNetworkConsent } = await import('./license')
+ initLicense()
+ await refreshed() // no consent yet → no request
+ expect(fetchMock).not.toHaveBeenCalled()
+ setLicenseNetworkConsent(() => true)
+ fetchMock.mockResolvedValue(jsonResponse({ key: 'K', used: 1, seats: 3, source: 'keygen' }))
+ const d = (await fake.handlers[IPC.licenseDetail]()) as LicenseDetail
+ expect(d.error).toBeNull()
+ expect(urls()).toEqual(['http://127.0.0.1:1/v1/license/detail'])
+ })
+ })
+})
diff --git a/src/core/license.ts b/src/core/license.ts
index 469680f4a..5618351e3 100644
--- a/src/core/license.ts
+++ b/src/core/license.ts
@@ -28,12 +28,51 @@ const SEATS_CHECKOUT_URL = process.env.NODETERM_SEATS_CHECKOUT_URL || 'https://b
// silently drop Pro. Re-refresh on the same 6h cadence as the check/update polls.
const REFRESH_INTERVAL_MS = 6 * 60 * 60 * 1000
-// Same gate as telemetry/check: never hit the prod API from a dev/unsigned build unless a
-// local server is targeted explicitly, and honor DO_NOT_TRACK / the kill switch.
+/** DO_NOT_TRACK or the telemetry kill switch is set (read live, like every other env guard here). */
+export function isDntEnv(): boolean {
+ return !!(process.env.DO_NOT_TRACK || process.env.NODETERM_TELEMETRY_DISABLED)
+}
+
+// The user's consent to license calls while DO_NOT_TRACK is set (spec §7.4: a setting shown and
+// revocable in Settings → Privacy, wired in by the shell). Unwired — the default, and any shell that
+// never wires it — there is no consent, which is the pre-consent behavior: no license call under DNT.
+let networkConsent: () => boolean = () => false
+
+/**
+ * Install the consent callback. It is read on EVERY gated call, so revoking consent takes effect at
+ * once. Only callers of `licenseNetworkGate()` honor it — the license routes in this file, and the
+ * project-limit claim (spec §7.4) — never telemetry or the check feed, which keep their own
+ * unconditional DNT guard.
+ */
+export function setLicenseNetworkConsent(fn: () => boolean): void {
+ networkConsent = fn
+}
+
+/** Why a license call may not run. The non-`ok` words are also `ClaimError`s (shared/project-limit). */
+export type LicenseNetworkGate = 'ok' | 'consent_required' | 'disabled'
+
+/**
+ * Whether a license call may reach the API. `disabled`: a dev/unsigned build never hits the prod API
+ * unless a local server is targeted explicitly (the same build rule as telemetry/check).
+ * `consent_required`: DO_NOT_TRACK / the kill switch is set and the user has not consented. A consent
+ * callback that throws reads as no consent — the direction that sends nothing.
+ */
+export function licenseNetworkGate(): LicenseNetworkGate {
+ if (!platform().isPackaged && !process.env.NODETERM_API_BASE) return 'disabled'
+ if (isDntEnv()) {
+ let consented = false
+ try {
+ consented = networkConsent()
+ } catch {
+ // fall through: no consent
+ }
+ return consented ? 'ok' : 'consent_required'
+ }
+ return 'ok'
+}
+
function allowed(): boolean {
- if (process.env.DO_NOT_TRACK || process.env.NODETERM_TELEMETRY_DISABLED) return false
- if (!platform().isPackaged && !process.env.NODETERM_API_BASE) return false
- return true
+ return licenseNetworkGate() === 'ok'
}
interface Stored {
@@ -61,6 +100,15 @@ async function save(s: Stored): Promise<void> {
await fs.writeFile(file(), JSON.stringify(s), 'utf-8').catch(() => {})
}
+/**
+ * The clock-rollback anchor (ms): the later of the wall clock and the largest timestamp this install
+ * has observed (`lastSeen`). Every expiry here is compared against it, never the bare wall clock, so
+ * setting the system clock back cannot revive an expired token.
+ */
+export function clockAnchorMs(): number {
+ return Math.max(Date.now(), (load().lastSeen ?? 0) * 1000)
+}
+
interface Payload {
deviceId: string
tier: string
@@ -81,8 +129,9 @@ export const PRO_FREE_SEATS = 3
// Beyond the signature, the token must be minted for THIS machine (a copied license.json
// from another install must not validate), and its expiry is checked against the largest
// timestamp we've ever observed — not just Date.now() — so rolling the system clock back
-// can't revive an expired token (see lastSeen).
-function verify(token: string | undefined): Payload | null {
+// can't revive an expired token (see clockAnchorMs). `graceMs` accepts a token that expired
+// less than that long ago; every caller but proForProjectLimit passes none.
+function verify(token: string | undefined, graceMs = 0): Payload | null {
if (!token || !ENTITLEMENT_PUBLIC_KEY) return null
const dot = token.indexOf('.')
if (dot < 1) return null
@@ -93,8 +142,7 @@ function verify(token: string | undefined): Payload | null {
if (!crypto.verify(null, Buffer.from(p), key, Buffer.from(s, 'base64url'))) return null
const payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf-8')) as Payload
if (payload.deviceId !== getDeviceId()) return null
- const now = Math.max(Date.now(), (load().lastSeen ?? 0) * 1000)
- if (typeof payload.exp !== 'number' || payload.exp * 1000 <= now) return null
+ if (typeof payload.exp !== 'number' || payload.exp * 1000 <= clockAnchorMs() - graceMs) return null
return payload
} catch {
return null
@@ -250,6 +298,24 @@ export function isPremium(): boolean {
return verify(load().token) !== null
}
+/** How long past its expiry a stored entitlement still counts as Pro — for the project limit only. */
+export const PRO_LIMIT_GRACE_MS = 30 * 24 * 60 * 60 * 1000
+
+/**
+ * Pro for the purposes of the free-tier open-project limit (spec §6), and for NOTHING else — every
+ * other Pro feature gates on `isPremium()`. True when `isPremium()` is, or when the stored token
+ * passes the same signature + deviceId verification and expired less than `PRO_LIMIT_GRACE_MS` ago
+ * by the clock anchor. A paying user offline past the 7-day token TTL must not be blocked from
+ * opening a project; the cost is that cancelling and then blocking the API buys at most 30 days.
+ *
+ * "No 2xx `active:false` since" needs no record of its own: the device-bound refresh deletes the
+ * stored token on exactly that answer, so a token still on disk means the server has not said
+ * inactive since it was minted.
+ */
+export function proForProjectLimit(): boolean {
+ return isPremium() || verify(load().token, PRO_LIMIT_GRACE_MS) !== null
+}
+
// Every refresh started so far (the launch one + whatever the 6h interval fired), chained. The
// refresh is deliberately fire-and-forget — nothing at boot may block on the network — which has
// two consequences this handle exists to own: