diff --git a/docs/examples/analytics/observe/v1/umami-adapter.mjs b/docs/examples/analytics/observe/v1/umami-adapter.mjs index a82f39e45..23241a20c 100644 --- a/docs/examples/analytics/observe/v1/umami-adapter.mjs +++ b/docs/examples/analytics/observe/v1/umami-adapter.mjs @@ -26,7 +26,21 @@ export function createUmamiAdapter({ window: win = window, document: doc = docum script.onload = script.onerror = null finishLoad(ok) } - win.skillhubUmamiBeforeSend = (type, payload) => stopped ? null : sanitizeUmamiPayload(type, payload, website) + win.skillhubUmamiBeforeSend = (type, payload) => { + if (stopped) return null + const sanitized = sanitizeUmamiPayload(type, payload, website) + if (!sanitized) return null + // Verified against pinned v3.4.1: serialization is synchronous at fetch dispatch, + // inside the SDK's try/catch, after awaiting this hook. Re-verify on SDK upgrades. + Object.defineProperty(sanitized, 'toJSON', { + enumerable: false, + value() { + if (stopped) throw new Error('Analytics stopped before dispatch') + return { website: sanitized.website, name: sanitized.name, data: { event: sanitized.data.event } } + }, + }) + return sanitized + } script.src = `${prefix}/script.js` script.async = true script.setAttribute('data-website-id', website) @@ -63,8 +77,8 @@ export function createUmamiAdapter({ window: win = window, document: doc = docum stopped = true loaded(false) script.remove() - // Keep a denying hook: a tracker already loaded cannot bypass consent withdrawal. - // Requests already handed to fetch cannot be recalled. + // Keep the denying hook and dispatch guard: no new request after stop returns. + // Only a request whose fetch already started cannot be recalled. }, } } diff --git a/docs/frontend-analytics.md b/docs/frontend-analytics.md index 7f20ca30b..218ff12fc 100644 --- a/docs/frontend-analytics.md +++ b/docs/frontend-analytics.md @@ -247,7 +247,14 @@ load failure, timeout or `stop()`. Once ready, every valid intent calls the trac independently: concurrent or hung requests do not block later intents. Each call's wait is time-bounded; missing, blocked, throwing or rejecting trackers resolve silently. There is no retry, durable queue or post-load backlog; best-effort counts -can undercount. A timeout cannot cancel an SDK fetch already in flight. +can undercount. After `stop()` returns, no new request is dispatched; only a +request whose fetch already started cannot be recalled (nor cancelled by a timeout). +The before-send hook keeps its immediate stop check and adds a non-enumerable +`toJSON` guard that re-checks consent when the SDK serializes at dispatch. In pinned +v3.4.1 this runs synchronously in the fetch expression inside the SDK's try/catch: +throwing on stop prevents fetch and is swallowed by the SDK. This relies on that +ordering; a different Umami version must re-verify it with the dispatch-boundary +regression tests in `web/analytics-umami-example.test.ts`. The sanitizer allowlists the FINAL SDK payload, not just the callback. Only `{ type: 'event', payload: { website, name, data: { event } } }` survives; website @@ -280,8 +287,11 @@ analytics DB, persistent queue or multi-vendor SDK is introduced. No injection means zero collection. `enabled: false` in the deployer's entry is also inert: no helper initialization or tracker load. On consent withdrawal call -`window.skillhubAnalytics.stop()`; it removes listeners and denies future SDK -payloads (already-sent requests cannot be recalled). Resume only after approval +`window.skillhubAnalytics.stop()`; it removes listeners and denies SDK payloads, +including those awaiting dispatch. After it returns, no new request is dispatched; +only a request whose fetch already started cannot be recalled. The dispatch guard +relies on pinned v3.4.1 serializing at dispatch; re-run the adapter regression tests +to re-verify this ordering for a different Umami version. Resume only after approval via `start()`. Platform-side disabling/deleting the website, Umami's local `umami.disabled` switch, or blocking the two ingestion routes are additional operator controls, not substitutes for consent. Removing injection and purging diff --git a/web/analytics-umami-example.test.ts b/web/analytics-umami-example.test.ts index bb30a378b..4dd30e18a 100644 --- a/web/analytics-umami-example.test.ts +++ b/web/analytics-umami-example.test.ts @@ -45,6 +45,88 @@ describe('product ID grammar parity', () => { }) }) +describe('Umami v3.4.1 dispatch-time consent boundary', () => { + function platform(fetch = vi.fn().mockResolvedValue(undefined)) { + let approved: unknown + const win = { + skillhubUmamiBeforeSend: undefined as unknown, + umami: { track: async (name: string, data: { event: string }) => { + const type = 'event', endpoint = '/_skillhub-umami/api/send' + let payload: unknown = { website, name, data, url: '/private', title: 'private' } + const callback = (type: string, payload: unknown) => { + approved = (win.skillhubUmamiBeforeSend as (type: string, payload: unknown) => unknown)(type, payload) + return approved + } + // Mirror pinned v3.4.1 send(): await before-send, null check, then + // serialize synchronously in the fetch expression inside its try/catch. + payload = await Promise.resolve(callback(type, payload)) + if (!payload) return + try { + await fetch(endpoint, { body: JSON.stringify({ type, payload }) }) + } catch { /* SDK swallows serialization and transport failures. */ } + } }, + } + const adapter = createUmamiAdapter({ window: win, document, website }) + document.querySelector('script')!.dispatchEvent(new Event('load')) + return { adapter, fetch, approved: () => approved } + } + + it('stop in the before-send/fetch microtask gap dispatches nothing and send resolves without unhandled rejection', async () => { + const { adapter, fetch, approved } = platform() + const unhandled = vi.fn() + window.addEventListener('unhandledrejection', unhandled) + try { + const pending = adapter.send(intent) + await Promise.resolve() + expect(approved()).toEqual({ website, name: intent.id, data: { event: 'click' } }) + expect(fetch).not.toHaveBeenCalled() + adapter.stop() + await expect(pending).resolves.toBeUndefined() + await new Promise(resolve => window.setTimeout(resolve, 0)) + expect(fetch).not.toHaveBeenCalled() + expect(unhandled).not.toHaveBeenCalled() + } finally { + adapter.stop() + window.removeEventListener('unhandledrejection', unhandled) + } + }) + + it('stop in a later macrotask lets an already-started fetch complete but dispatches no more', async () => { + let complete!: () => void + const fetch = vi.fn(() => new Promise(resolve => { complete = resolve })) + const { adapter } = platform(fetch) + try { + const pending = adapter.send(intent) + await new Promise(resolve => window.setTimeout(resolve, 0)) + expect(fetch).toHaveBeenCalledTimes(1) + adapter.stop() + complete() + await expect(pending).resolves.toBeUndefined() + await expect(adapter.send(intent)).resolves.toBeUndefined() + expect(fetch).toHaveBeenCalledTimes(1) + } finally { adapter.stop() } + }) + + it('serializes the exact allowlisted envelope and keeps toJSON non-enumerable', async () => { + const { adapter, fetch, approved } = platform() + try { + await expect(adapter.send(intent)).resolves.toBeUndefined() + expect(fetch).toHaveBeenCalledExactlyOnceWith('/_skillhub-umami/api/send', { + body: `{"type":"event","payload":{"website":"${website}","name":"${intent.id}","data":{"event":"click"}}}`, + }) + expect(Object.keys(approved() as object)).toEqual(['website', 'name', 'data']) + expect(Object.getOwnPropertyDescriptor(approved(), 'toJSON')).toMatchObject({ enumerable: false, value: expect.any(Function) }) + const guarded = approved() as { toJSON: () => { data: object } } + const first = guarded.toJSON(), second = guarded.toJSON() + expect(first).toEqual({ website, name: intent.id, data: { event: 'click' } }) + expect(Object.getPrototypeOf(first)).toBe(Object.prototype) + expect(first).not.toBe(second) + expect(first.data).not.toBe(second.data) + expect(Object.getOwnPropertyNames(first)).toEqual(['website', 'name', 'data']) + } finally { adapter.stop() } + }) +}) + describe('Umami v3.4.1 adapter', () => { it('allowlists the FINAL payload, never SDK context or extra data', () => { expect(sanitizeUmamiPayload('event', {