diff --git a/docs/examples/analytics/observe/v1/umami-adapter.mjs b/docs/examples/analytics/observe/v1/umami-adapter.mjs index 23241a20c..15eace3b1 100644 --- a/docs/examples/analytics/observe/v1/umami-adapter.mjs +++ b/docs/examples/analytics/observe/v1/umami-adapter.mjs @@ -6,10 +6,16 @@ const events = ['click', 'submit', 'keydown'] // Umami's before-send hook returns the inner payload, not the { type, payload } envelope. export function sanitizeUmamiPayload(type, payload, website) { - if (type !== 'event' || !websiteShape.test(website) || payload?.website !== website - || typeof payload?.name !== 'string' || !idShape.test(payload.name) - || payload.name.length > 50 || !events.includes(payload.data?.event)) return null - return { website, name: payload.name, data: { event: payload.data.event } } + let payloadWebsite, name, event + try { + payloadWebsite = payload?.website + name = payload?.name + event = payload?.data?.event + } catch { return null } + if (type !== 'event' || !websiteShape.test(website) || payloadWebsite !== website + || typeof name !== 'string' || !idShape.test(name) || name.length > 50 + || typeof event !== 'string' || !events.includes(event)) return null + return { website: payloadWebsite, name, data: { event } } } export function createUmamiAdapter({ window: win = window, document: doc = document, @@ -30,13 +36,14 @@ export function createUmamiAdapter({ window: win = window, document: doc = docum if (stopped) return null const sanitized = sanitizeUmamiPayload(type, payload, website) if (!sanitized) return null + const { website: validatedWebsite, name, data: { event } } = sanitized // 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 { website: validatedWebsite, name, data: { event } } }, }) return sanitized diff --git a/docs/frontend-analytics.md b/docs/frontend-analytics.md index 218ff12fc..8a1b23cbb 100644 --- a/docs/frontend-analytics.md +++ b/docs/frontend-analytics.md @@ -262,6 +262,7 @@ must match configuration, name must match the ID shape (and Umami's 50-character limit), event must be click/submit/keydown. It returns null for pageviews (including unnamed `event` payloads), identify, performance and everything else. Hostname, URL, title, referrer, screen, language, tag, identity and extra data keys are removed. +Values are read once, and only validated primitives are forwarded. The SDK still reads title/URL/referrer in-page before sanitizing; it also reads localStorage for its own `umami.disabled` switch. Those are SDK behaviors, not behaviors of the vendor-neutral helper. diff --git a/web/analytics-umami-example.test.ts b/web/analytics-umami-example.test.ts index 4dd30e18a..7b21462a7 100644 --- a/web/analytics-umami-example.test.ts +++ b/web/analytics-umami-example.test.ts @@ -50,9 +50,11 @@ describe('Umami v3.4.1 dispatch-time consent boundary', () => { let approved: unknown const win = { skillhubUmamiBeforeSend: undefined as unknown, - umami: { track: async (name: string, data: { event: string }) => { + umami: { track: async (name: string | object | (() => object), data?: { event: string }) => { const type = 'event', endpoint = '/_skillhub-umami/api/send' - let payload: unknown = { website, name, data, url: '/private', title: 'private' } + // Pinned track(object) shallow-copies; track(function) preserves its result's accessors. + let payload: unknown = typeof name === 'string' ? { website, name, data, url: '/private', title: 'private' } + : typeof name === 'function' ? name() : { ...name } const callback = (type: string, payload: unknown) => { approved = (win.skillhubUmamiBeforeSend as (type: string, payload: unknown) => unknown)(type, payload) return approved @@ -68,9 +70,82 @@ describe('Umami v3.4.1 dispatch-time consent boundary', () => { } const adapter = createUmamiAdapter({ window: win, document, website }) document.querySelector('script')!.dispatchEvent(new Event('load')) - return { adapter, fetch, approved: () => approved } + return { adapter, fetch, approved: () => approved, track: win.umami.track } } + it.each([ + ['event', 'string'], ['event', 'toJSON'], ['name', 'string'], ['name', 'toJSON'], + ])('snapshots a changing %s getter before its second %s value can leak or stop then dispatch', async (field, mode) => { + let stopReturned = false, dispatchedAfterStop = false, reads = 0 + const fetch = vi.fn(async () => { if (stopReturned) dispatchedAfterStop = true }) + const { adapter, track } = platform(fetch) + const lateValue = mode === 'string' ? 'PRIVATE VALUE' : { + toJSON() { adapter.stop(); stopReturned = true; return { secret: 'PRIVATE VALUE' } }, + } + const payload = { website, name: intent.id, data: { event: 'click' } } + Object.defineProperty(field === 'name' ? payload : payload.data, field, { + enumerable: true, + get() { return ++reads === 1 ? (field === 'name' ? intent.id : 'click') : lateValue }, + }) + try { + // Object path retains nested event accessors; function path retains name accessors. + await expect(track(field === 'name' ? () => payload : payload)).resolves.toBeUndefined() + expect(dispatchedAfterStop).toBe(false) + expect(fetch.mock.calls.length).toBeLessThanOrEqual(1) + for (const call of fetch.mock.calls as unknown as Array<[string, { body: string }]>) { + expect(call[1].body).toBe(JSON.stringify({ type: 'event', payload: { website, name: intent.id, data: { event: 'click' } } })) + expect(call[1].body).not.toContain('PRIVATE') + } + expect(reads).toBe(1) + adapter.stop(); stopReturned = true + await track(intent.id, { event: 'click' }) + expect(dispatchedAfterStop).toBe(false) + } finally { adapter.stop() } + }) + + it.each(['website', 'name', 'data', 'event'])('drops a throwing %s getter without sending or unhandled rejection', async field => { + const { adapter, fetch, track } = platform() + const unhandled = vi.fn() + window.addEventListener('unhandledrejection', unhandled) + const payload = { website, name: intent.id, data: { event: 'click' } } + Object.defineProperty(field === 'event' ? payload.data : payload, field, { + get() { throw Error('unreadable payload') }, + }) + try { + expect(sanitizeUmamiPayload('event', payload, website)).toBeNull() + await expect(track(() => payload)).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('reads website/name/data/event once and serializes only captured primitives despite returned-object mutation', async () => { + const { adapter, fetch, track, approved } = platform() + const getters = { + website: vi.fn(() => website), name: vi.fn(() => intent.id), event: vi.fn(() => 'click'), + data: vi.fn(() => Object.defineProperty({}, 'event', { get: getters.event })), + } + const payload = Object.defineProperties({}, { + website: { get: getters.website }, name: { get: getters.name }, data: { get: getters.data }, + }) + try { + const pending = track(() => payload) + const guarded = approved() as object + for (const field of ['website', 'name', 'data']) { + Object.defineProperty(guarded, field, { get() { throw Error('must not re-read returned object') } }) + } + await expect(pending).resolves.toBeUndefined() + expect(fetch).toHaveBeenCalledExactlyOnceWith('/_skillhub-umami/api/send', { + body: JSON.stringify({ type: 'event', payload: { website, name: intent.id, data: { event: 'click' } } }), + }) + for (const getter of Object.values(getters)) expect(getter).toHaveBeenCalledTimes(1) + } finally { adapter.stop() } + }) + 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()