fix(analytics): guard consent at Umami dispatch boundary

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>
This commit is contained in:
千乘妍 (Xiaoyaner) 2026-10-26 14:17:51 +08:00
parent 1936cee3cc
commit 2aecb6183c
3 changed files with 112 additions and 6 deletions

View file

@ -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.
},
}
}

View file

@ -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

View file

@ -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<void>(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', {