diff --git a/src/workbench/extensions/agent/crdt/__fixtures__/docFrameClient.ts b/src/workbench/extensions/agent/crdt/__fixtures__/docFrameClient.ts new file mode 100644 index 00000000000..64580c8ce90 --- /dev/null +++ b/src/workbench/extensions/agent/crdt/__fixtures__/docFrameClient.ts @@ -0,0 +1,41 @@ +type ServerFrameType = + | 'doc_update' + | 'doc_subscribed' + | 'doc_ops_result' + | 'doc_reset' + | 'awareness' + +function serverFrame( + type: T, + data: Record +) { + return { + type, + data: { v: 1, workflow_id: 'wf-1', ...data } + } +} + +export function docUpdateFrame(data: Record = {}) { + return serverFrame('doc_update', { seq: 1, update_b64: 'AQ==', ...data }) +} + +export function docSubscribedFrame(data: Record = {}) { + return serverFrame('doc_subscribed', { ok: true, seq: 1, ...data }) +} + +export function docOpsResultFrame(data: Record = {}) { + return serverFrame('doc_ops_result', { ok: true, ...data }) +} + +export function docResetFrame(data: Record = {}) { + return serverFrame('doc_reset', { seq: 1, actor: 'system:mint', ...data }) +} + +export function awarenessFrame(data: Record = {}) { + return serverFrame('awareness', { + actor: 'human:user:tab-a', + state: {}, + expires_at: 123, + ...data + }) +} diff --git a/src/workbench/extensions/agent/crdt/docFrameClient.arrays.test.ts b/src/workbench/extensions/agent/crdt/docFrameClient.arrays.test.ts new file mode 100644 index 00000000000..752fb6d3153 --- /dev/null +++ b/src/workbench/extensions/agent/crdt/docFrameClient.arrays.test.ts @@ -0,0 +1,252 @@ +import { describe, expect, it } from 'vitest' + +import { + docOpsResultFrame, + docUpdateFrame +} from './__fixtures__/docFrameClient' +import { parseServerDocFrame } from './docFrameClient' + +function resultFrame(data: Record) { + return parseServerDocFrame(docOpsResultFrame(data)) +} + +const invalidResultFrames: [string, Record][] = [ + ['a non-string applied item', { ok: true, seq: 1, applied: ['op-1', 2] }], + ['a non-string skipped item', { ok: true, seq: 1, skipped: ['op-1', 2] }], + [ + 'a failure without an index', + { + ok: true, + seq: 1, + failed: { + op_id: 'op-1', + code: 'invalid_op', + message: 'invalid operation' + } + } + ], + [ + 'a non-string failure op_id', + { + ok: true, + seq: 1, + failed: { + index: 0, + op_id: 1, + code: 'invalid_op', + message: 'invalid operation' + } + } + ], + ['a non-array applied value', { ok: true, seq: 1, applied: 'op-1' }], + ['a non-string error code', { ok: false, code: 1 }], + ['a non-numeric sequence', { ok: true, seq: '1' }], + ['an oversized operation identity', { ok: true, applied: ['x'.repeat(129)] }], + ['an oversized error code', { ok: false, code: 'x'.repeat(129) }], + [ + 'an oversized error message', + { ok: false, message: 'x'.repeat((8 << 10) + 1) } + ], + [ + 'too many operation identities', + { ok: true, applied: Array.from({ length: 257 }, () => 'x') } + ] +] + +describe('document frame result arrays and acknowledgements', () => { + it('rejects a doc_update with a non-string op id', () => { + expect( + parseServerDocFrame(docUpdateFrame({ op_ids: ['op-1', 2] })) + ).toBeNull() + }) + + it('treats null doc_update op ids as absent', () => { + expect(parseServerDocFrame(docUpdateFrame({ op_ids: null }))).toEqual({ + type: 'doc_update', + data: { + workflowId: 'wf-1', + seq: 1, + update: new Uint8Array([1]) + } + }) + }) + + it.for(invalidResultFrames)('rejects %s', ([_name, data]) => { + expect(resultFrame(data)).toBeNull() + }) + + it('accepts a failure without an op_id (relay omits it when unmapped)', () => { + expect( + resultFrame({ + ok: false, + code: 'invalid_op', + message: 'invalid operation', + failed: { index: 0, code: 'invalid_op', message: 'invalid operation' } + }) + ).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: false, + applied: [], + skipped: [], + code: 'invalid_op', + message: 'invalid operation', + failed: { index: 0, code: 'invalid_op', message: 'invalid operation' } + } + }) + }) + + it('accepts a successful acknowledgement without a sequence', () => { + expect(resultFrame({ ok: true })).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: true, + applied: [], + skipped: [] + } + }) + }) + + it('accepts a failed acknowledgement without a code', () => { + expect(resultFrame({ ok: false, message: 'batch rejected' })).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: false, + applied: [], + skipped: [], + message: 'batch rejected' + } + }) + }) + + // The relay serialises applied/skipped with `omitempty`: rejections carry + // neither, a fully-applied batch carries no `skipped`, and an all-redelivery + // no-op carries no `applied`. Absent must read as empty, not malformed. + it('accepts a relay rejection that omits applied and skipped', () => { + expect( + resultFrame({ ok: false, code: 'invalid_frame', message: 'bad frame' }) + ).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: false, + applied: [], + skipped: [], + code: 'invalid_frame', + message: 'bad frame' + } + }) + }) + + it('accepts a fully applied acknowledgement that omits skipped', () => { + expect(resultFrame({ ok: true, seq: 7, applied: ['op-1'] })).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: true, + seq: 7, + applied: ['op-1'], + skipped: [] + } + }) + }) + + it('accepts an all-redelivery acknowledgement that omits applied', () => { + expect(resultFrame({ ok: true, seq: 7, skipped: ['op-1'] })).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: true, + seq: 7, + applied: [], + skipped: ['op-1'] + } + }) + }) + + it('treats null result arrays as absent', () => { + expect(resultFrame({ ok: true, seq: 1, skipped: null })).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: true, + seq: 1, + applied: [], + skipped: [] + } + }) + }) + + it('accepts strictly typed result arrays and failure data', () => { + expect( + resultFrame({ + ok: false, + applied: ['op-1'], + skipped: ['op-2'], + code: 'invalid_op', + message: 'invalid operation', + failed: { + index: 2, + op_id: 'op-3', + code: 'invalid_op', + message: 'invalid operation' + } + }) + ).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: false, + applied: ['op-1'], + skipped: ['op-2'], + code: 'invalid_op', + message: 'invalid operation', + failed: { + index: 2, + op_id: 'op-3', + code: 'invalid_op', + message: 'invalid operation' + } + } + }) + }) + + it('strips unrecognized failure properties', () => { + expect( + resultFrame({ + ok: false, + failed: { + index: 0, + op_id: 'op-1', + code: 'invalid_op', + message: 'invalid operation', + private_context: 'must not escape the parser' + } + }) + ).toMatchObject({ + data: { + failed: { + index: 0, + op_id: 'op-1', + code: 'invalid_op', + message: 'invalid operation' + } + } + }) + expect( + resultFrame({ + ok: false, + failed: { + index: 0, + op_id: 'op-1', + code: 'invalid_op', + message: 'invalid operation', + private_context: 'must not escape the parser' + } + })?.data + ).not.toHaveProperty('failed.private_context') + }) +}) diff --git a/src/workbench/extensions/agent/crdt/docFrameClient.awareness.test.ts b/src/workbench/extensions/agent/crdt/docFrameClient.awareness.test.ts index 91aa6fb64ec..1aae80dc08a 100644 --- a/src/workbench/extensions/agent/crdt/docFrameClient.awareness.test.ts +++ b/src/workbench/extensions/agent/crdt/docFrameClient.awareness.test.ts @@ -1,48 +1,45 @@ import { describe, expect, it } from 'vitest' +import { awarenessFrame } from './__fixtures__/docFrameClient' import { parseServerDocFrame } from './docFrameClient' -function awarenessFrame(state: unknown, expiresAt: unknown = 123) { - return { - type: 'awareness', - data: { - v: 1, - workflow_id: 'wf-1', - actor: 'human:user:tab-a', - state, - expires_at: expiresAt - } - } -} +const invalidAwarenessFrames: [string, unknown, unknown][] = [ + ['an oversized state', { value: 'x'.repeat(8 * 1024) }, 123], + ['an array state', ['cursor', 10, 20], 123], + ['a negative expiry', {}, -1], + ['an infinite expiry', {}, Number.POSITIVE_INFINITY], + ['a NaN expiry', {}, Number.NaN], + ['a fractional expiry', {}, 1.5], + ['an unsafe expiry', {}, Number.MAX_SAFE_INTEGER + 1], + ['an extremely large expiry', {}, 1e300], + ['an unserializable state', { value: 1n }, 123] +] describe('awareness frame validation', () => { - it('rejects state whose JSON encoding exceeds 8 KiB', () => { + it.for(invalidAwarenessFrames)('rejects %s', ([_name, state, expiresAt]) => { expect( - parseServerDocFrame(awarenessFrame({ value: 'x'.repeat(8 * 1024) })) + parseServerDocFrame(awarenessFrame({ state, expires_at: expiresAt })) ).toBeNull() }) it('accepts state whose JSON encoding is exactly 8 KiB', () => { - // `{"value":"x…"}` wraps the string in 12 bytes of JSON syntax. const state = { value: 'x'.repeat(8 * 1024 - 12) } expect(new TextEncoder().encode(JSON.stringify(state)).byteLength).toBe( 8 * 1024 ) - expect(parseServerDocFrame(awarenessFrame(state))).toMatchObject({ + expect(parseServerDocFrame(awarenessFrame({ state }))).toMatchObject({ data: { state } }) }) - it('rejects array-shaped state', () => { - expect(parseServerDocFrame(awarenessFrame(['cursor', 10, 20]))).toBeNull() - }) - it('treats a null state as absent rather than rejecting the frame', () => { // The Go server's `State map[string]any` has `omitempty` and never // actually emits `state: null`, but this is defence in depth: null // should fold into "no state", not discard the whole frame (and with // it actor/expires_at). discussion_r3911665011. - expect(parseServerDocFrame(awarenessFrame(null, 456))).toEqual({ + expect( + parseServerDocFrame(awarenessFrame({ state: null, expires_at: 456 })) + ).toEqual({ type: 'awareness', data: { workflowId: 'wf-1', @@ -52,30 +49,10 @@ describe('awareness frame validation', () => { }) }) - it('rejects negative expires_at', () => { - expect(parseServerDocFrame(awarenessFrame({}, -1))).toBeNull() - }) - - it('rejects non-finite expires_at', () => { - expect( - parseServerDocFrame(awarenessFrame({}, Number.POSITIVE_INFINITY)) - ).toBeNull() - expect(parseServerDocFrame(awarenessFrame({}, Number.NaN))).toBeNull() - }) - - it('rejects fractional expires_at', () => { - expect(parseServerDocFrame(awarenessFrame({}, 1.5))).toBeNull() - }) - - it('rejects expires_at beyond the safe integer range', () => { - expect( - parseServerDocFrame(awarenessFrame({}, Number.MAX_SAFE_INTEGER + 1)) - ).toBeNull() - expect(parseServerDocFrame(awarenessFrame({}, 1e300))).toBeNull() - }) - it('accepts a zero expires_at', () => { - expect(parseServerDocFrame(awarenessFrame({}, 0))).toMatchObject({ + expect( + parseServerDocFrame(awarenessFrame({ expires_at: 0 })) + ).toMatchObject({ data: { expiresAt: 0 } }) }) @@ -83,7 +60,10 @@ describe('awareness frame validation', () => { it('accepts a valid awareness frame', () => { expect( parseServerDocFrame( - awarenessFrame({ cursor: [10, 20], selection: 'node-1' }, 456) + awarenessFrame({ + state: { cursor: [10, 20], selection: 'node-1' }, + expires_at: 456 + }) ) ).toEqual({ type: 'awareness', diff --git a/src/workbench/extensions/agent/crdt/docFrameClient.base64.test.ts b/src/workbench/extensions/agent/crdt/docFrameClient.base64.test.ts new file mode 100644 index 00000000000..3ad2e0a8b9b --- /dev/null +++ b/src/workbench/extensions/agent/crdt/docFrameClient.base64.test.ts @@ -0,0 +1,48 @@ +import { describe, expect, it } from 'vitest' + +import { docUpdateFrame } from './__fixtures__/docFrameClient' +import { parseServerDocFrame } from './docFrameClient' + +const invalidBase64: [string, string][] = [ + ['non-base64 characters', 'YQ$='], + ['truncated input', 'YQ='], + ['empty input', ''], + ['non-canonical padding bits (RFC 4648 §3.5)', 'YR=='] +] + +describe('parseServerDocFrame doc_update base64 validation', () => { + it.for(invalidBase64)('rejects %s without throwing', ([_name, encoded]) => { + expect(() => + parseServerDocFrame(docUpdateFrame({ update_b64: encoded })) + ).not.toThrow() + expect( + parseServerDocFrame(docUpdateFrame({ update_b64: encoded })) + ).toBeNull() + }) + + it('rejects decoded updates larger than 8 MiB without throwing', () => { + const encoded = 'AAAA'.repeat((8 * 1024 * 1024 + 1) / 3) + + expect(() => + parseServerDocFrame(docUpdateFrame({ update_b64: encoded })) + ).not.toThrow() + expect( + parseServerDocFrame(docUpdateFrame({ update_b64: encoded })) + ).toBeNull() + }) + + it('accepts a decoded update at exactly 8 MiB', () => { + const maxBytes = 8 * 1024 * 1024 + const encoded = 'AAAA'.repeat(Math.floor(maxBytes / 3)) + 'AAA=' + + expect( + parseServerDocFrame(docUpdateFrame({ update_b64: encoded })) + ).not.toBeNull() + }) + + it('accepts canonical padding for the same byte', () => { + const parsed = parseServerDocFrame(docUpdateFrame({ update_b64: 'YQ==' })) + expect(parsed).not.toBeNull() + expect(parsed?.type).toBe('doc_update') + }) +}) diff --git a/src/workbench/extensions/agent/crdt/docFrameClient.grammar.test.ts b/src/workbench/extensions/agent/crdt/docFrameClient.grammar.test.ts new file mode 100644 index 00000000000..ac53986ab5a --- /dev/null +++ b/src/workbench/extensions/agent/crdt/docFrameClient.grammar.test.ts @@ -0,0 +1,52 @@ +import { describe, expect, it } from 'vitest' + +import { + awarenessFrame, + docOpsResultFrame, + docResetFrame, + docSubscribedFrame, + docUpdateFrame +} from './__fixtures__/docFrameClient' +import { parseServerDocFrame } from './docFrameClient' + +const validFrames = [ + docUpdateFrame({ + workflow_id: 'workflow_1-ABC', + actor: 'agent:thread-1:turn-1' + }), + docSubscribedFrame({ workflow_id: 'workflow_1-ABC' }), + docOpsResultFrame({ workflow_id: 'workflow_1-ABC', seq: 1 }), + docResetFrame({ workflow_id: 'workflow_1-ABC' }), + awarenessFrame({ + workflow_id: 'workflow_1-ABC', + actor: 'human:user-1:tab-1' + }) +] + +const invalidWorkflowIds: [string, string][] = [ + ['an empty workflow_id', ''], + ['a workflow_id containing whitespace', 'workflow invalid'], + ['a workflow_id exceeding 128 encoded bytes', 'w'.repeat(129)], + ['a workflow_id containing invalid characters', 'workflow:invalid'] +] + +const invalidActors: [string, string][] = [ + ['an actor exceeding 256 encoded bytes', `human:${'u'.repeat(250)}:tab`], + ['an actor outside the closed actor grammar', 'operator:user:tab'] +] + +describe('document frame identifier grammar', () => { + it.for(invalidWorkflowIds)('rejects %s', ([_name, workflowId]) => { + expect( + parseServerDocFrame(docSubscribedFrame({ workflow_id: workflowId })) + ).toBeNull() + }) + + it.for(invalidActors)('rejects %s', ([_name, actor]) => { + expect(parseServerDocFrame(awarenessFrame({ actor }))).toBeNull() + }) + + it.for(validFrames)('accepts valid identifiers in $type', (frame) => { + expect(parseServerDocFrame(frame)).not.toBeNull() + }) +}) diff --git a/src/workbench/extensions/agent/crdt/docFrameClient.test.ts b/src/workbench/extensions/agent/crdt/docFrameClient.test.ts index 087a2a8661d..ef0ac933207 100644 --- a/src/workbench/extensions/agent/crdt/docFrameClient.test.ts +++ b/src/workbench/extensions/agent/crdt/docFrameClient.test.ts @@ -1,6 +1,9 @@ -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import * as Y from 'yjs' +import { reportError } from '@/platform/telemetry/reportError' + +import { docUpdateFrame } from './__fixtures__/docFrameClient' import type { DocFrameTransport } from './docFrameClient' import { DocFrameClient, @@ -10,6 +13,8 @@ import { import { FollowerDoc } from './followerDoc' import { LayoutFollowerBridge } from './layoutFollowerBridge' +vi.mock('@/platform/telemetry/reportError', () => ({ reportError: vi.fn() })) + class TestTransport extends EventTarget implements DocFrameTransport { readonly sent: string[] = [] @@ -42,13 +47,13 @@ describe('doc frame client', () => { workflow_id: 'wf-1', seq: 1, update_b64: encodeBase64(encoded), - actor: 'agent:turn-1', - op_ids: ['op-1', 42, 'op-2'] + actor: 'agent:thread-1:turn-1', + op_ids: ['op-1', 'op-2'] } }) expect(frame?.type).toBe('doc_update') if (frame?.type !== 'doc_update') throw new Error('Expected doc_update') - expect(frame.data.actor).toBe('agent:turn-1') + expect(frame.data.actor).toBe('agent:thread-1:turn-1') expect(frame.data.opIds).toEqual(['op-1', 'op-2']) const follower = new FollowerDoc() @@ -223,4 +228,135 @@ describe('doc frame client', () => { } }) }) + + it('keeps optional acknowledgement fields optional', () => { + expect( + parseServerDocFrame({ + type: 'doc_subscribed', + data: { v: 1, workflow_id: 'wf-1', ok: false, code: 'forbidden' } + }) + ).toEqual({ + type: 'doc_subscribed', + data: { workflowId: 'wf-1', ok: false, code: 'forbidden' } + }) + expect( + parseServerDocFrame({ + type: 'doc_subscribed', + data: { v: 1, workflow_id: 'wf-1', ok: true } + }) + ).toEqual({ + type: 'doc_subscribed', + data: { workflowId: 'wf-1', ok: true } + }) + expect( + parseServerDocFrame({ + type: 'doc_ops_result', + data: { v: 1, workflow_id: 'wf-1', ok: false, message: 'rejected' } + }) + ).toEqual({ + type: 'doc_ops_result', + data: { + workflowId: 'wf-1', + ok: false, + applied: [], + skipped: [], + message: 'rejected' + } + }) + }) + + it('drops malformed advisory actors without dropping effect frames', () => { + expect( + parseServerDocFrame({ + type: 'doc_update', + data: { + v: 1, + workflow_id: 'wf-1', + seq: 1, + update_b64: 'AQ==', + actor: 'unknown:value' + } + }) + ).toEqual({ + type: 'doc_update', + data: { workflowId: 'wf-1', seq: 1, update: Uint8Array.from([1]) } + }) + expect( + parseServerDocFrame({ + type: 'doc_reset', + data: { + v: 1, + workflow_id: 'wf-1', + seq: 2, + actor: 'unknown:value' + } + }) + ).toEqual({ + type: 'doc_reset', + data: { workflowId: 'wf-1', seq: 2 } + }) + }) + + it('treats null optional values as absent', () => { + expect( + parseServerDocFrame({ + type: 'doc_ops_result', + data: { + v: 1, + workflow_id: 'wf-1', + ok: false, + failed: null, + code: null, + message: null + } + }) + ).toEqual({ + type: 'doc_ops_result', + data: { workflowId: 'wf-1', ok: false, applied: [], skipped: [] } + }) + expect( + parseServerDocFrame({ + type: 'awareness', + data: { + v: 1, + workflow_id: 'wf-1', + actor: 'human:user:tab', + state: null, + expires_at: null + } + }) + ).toEqual({ + type: 'awareness', + data: { workflowId: 'wf-1', actor: 'human:user:tab' } + }) + }) + + it('reports the first malformed inbound frame per type', () => { + const transport = new TestTransport() + const client = new DocFrameClient(transport) + const listener = vi.fn() + client.addEventListener('doc_update', listener) + + const invalidUpdate = docUpdateFrame({ update_b64: 'not-base64' }).data + transport.receive('doc_update', invalidUpdate) + transport.receive('doc_update', invalidUpdate) + transport.receive('awareness', {}) + + expect(listener).not.toHaveBeenCalled() + expect(reportError).toHaveBeenCalledTimes(2) + expect(reportError).toHaveBeenCalledWith(expect.any(Error), { + errorType: 'agent_crdt_invalid_server_frame', + tags: { frame_type: 'doc_update' }, + level: 'warning' + }) + expect(reportError).toHaveBeenCalledWith(expect.any(Error), { + errorType: 'agent_crdt_invalid_server_frame', + tags: { frame_type: 'awareness' }, + level: 'warning' + }) + }) + + it.for([-1, 1.5])('rejects invalid sequence %s in doc_update', (seq) => { + expect(parseServerDocFrame(docUpdateFrame({ seq }))).toBeNull() + }) }) diff --git a/src/workbench/extensions/agent/crdt/docFrameClient.ts b/src/workbench/extensions/agent/crdt/docFrameClient.ts index 9917b4a4254..1203ae02566 100644 --- a/src/workbench/extensions/agent/crdt/docFrameClient.ts +++ b/src/workbench/extensions/agent/crdt/docFrameClient.ts @@ -1,7 +1,19 @@ import type { Op } from '@comfyorg/comfy-multi-player' +import { reportError } from '@/platform/telemetry/reportError' + const DOC_PROTOCOL_VERSION = 1 -const MAX_AWARENESS_STATE_BYTES = 8 * 1024 +const MAX_DOC_UPDATE_BYTES = 8 << 20 +const MAX_WORKFLOW_ID_LENGTH = 128 +const MAX_ACTOR_LENGTH = 256 +const MAX_AWARENESS_STATE_BYTES = 8 << 10 +const MAX_DOC_OPS_PER_FRAME = 256 +const MAX_OP_ID_LENGTH = 128 +const MAX_ERROR_CODE_LENGTH = 128 +const MAX_ERROR_MESSAGE_LENGTH = 8 << 10 +const BASE64_SINGLE_PADDING_END = /[AEIMQUYcgkosw048]=$/ +const BASE64_DOUBLE_PADDING_END = /[AQgw]==$/ +const utf8 = new TextEncoder() export interface DocOp { op_id: string @@ -26,6 +38,14 @@ export interface DocSubscribed { message?: string } +interface DocOpFailure { + index: number + /** Absent when the relay cannot map the failing index to an op id. */ + op_id?: string + code: string + message: string +} + interface DocOpsResult { workflowId: string ok: boolean @@ -34,11 +54,8 @@ interface DocOpsResult { skipped: string[] code?: string message?: string - /** - * PoC diagnostics: the batch's failure, forwarded verbatim. The wire type is - * a single object (`DocOpFailure {op_id, code, message}`), not an array. - */ - failed?: unknown + /** Validated diagnostics for the first rejected operation in a batch. */ + failed?: DocOpFailure } interface DocAwareness { @@ -100,11 +117,28 @@ interface WireData { failed?: unknown state?: unknown expires_at?: unknown + index?: unknown + op_id?: unknown } -function decodeBase64(value: string): Uint8Array { - const binary = atob(value) - return Uint8Array.from(binary, (character) => character.charCodeAt(0)) +function decodeBase64(value: string): Uint8Array | null { + if (value === '' || value.length % 4 !== 0) return null + const padding = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0 + if ((value.length / 4) * 3 - padding > MAX_DOC_UPDATE_BYTES) return null + + // `atob` is permissive about missing padding, so require canonical standard + // base64 before decoding the untrusted wire value. + if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return null + + if (padding === 2 && !BASE64_DOUBLE_PADDING_END.test(value)) return null + if (padding === 1 && !BASE64_SINGLE_PADDING_END.test(value)) return null + + try { + const binary = atob(value) + return Uint8Array.from(binary, (character) => character.charCodeAt(0)) + } catch { + return null + } } export function encodeBase64(value: Uint8Array): string { @@ -123,33 +157,101 @@ function parseRecord(value: unknown): Record | null { : null } -/** Unix seconds on the wire: a non-negative integer inside the safe range. */ -function isNonNegativeInteger(value: unknown): value is number { +function isAbsent(value: unknown): value is null | undefined { + return value === null || value === undefined +} + +function hasBoundedUtf8Length(value: string, maxBytes: number): boolean { + return value.length <= maxBytes && utf8.encode(value).length <= maxBytes +} + +function isValidWorkflowId(value: string): boolean { + return ( + value.length > 0 && + hasBoundedUtf8Length(value, MAX_WORKFLOW_ID_LENGTH) && + !/[\0\n\r\t :*?[\]]/.test(value) + ) +} + +function isValidActor(value: string): boolean { + if ( + value.length === 0 || + !hasBoundedUtf8Length(value, MAX_ACTOR_LENGTH) || + /[\0\n\r\t ]/.test(value) + ) + return false + if (value === 'system:mint') return true + const match = /^(?:agent|human):([^:]+):([^:]+)$/.exec(value) + return match !== null +} + +function isSequence(value: unknown): value is number { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 } -function parseAwarenessState( - value: unknown -): Record | undefined | null { - // The Go server's `State map[string]any` has `omitempty`, so it never - // emits `state: null` on the wire; nil/empty maps are omitted entirely, - // same as an absent field. Treat null the same as absent (no state) rather - // than rejecting the whole frame, so a value the server cannot actually - // send does not discard `actor`/`expires_at` too. A non-null, non-record - // shape (array, string, number) is still a malformed frame and rejected. - // discussion_r3911665011. - if (value === undefined || value === null) return undefined - const state = parseRecord(value) - if (state === null) return null - - // Defence in depth behind the server's identical cap. The counts are not - // byte-identical: Go's json.Marshal HTML-escapes `<`, `>` and `&`, so the - // server always counts >= this and is the stricter of the two. +function isStringArray(value: unknown): value is string[] { + return ( + Array.isArray(value) && + value.length <= MAX_DOC_OPS_PER_FRAME && + value.every( + (item) => + typeof item === 'string' && hasBoundedUtf8Length(item, MAX_OP_ID_LENGTH) + ) + ) +} + +function hasValidDiagnostics(data: WireData): boolean { + return ( + (isAbsent(data.code) || + (typeof data.code === 'string' && + hasBoundedUtf8Length(data.code, MAX_ERROR_CODE_LENGTH))) && + (isAbsent(data.message) || + (typeof data.message === 'string' && + hasBoundedUtf8Length(data.message, MAX_ERROR_MESSAGE_LENGTH))) + ) +} + +/** + * The relay serialises `applied`/`skipped` with `omitempty`, so an empty list + * arrives as an absent field. Absent means empty; present-but-malformed is a + * protocol violation. + */ +function parseOptionalStringArray(value: unknown): string[] | null { + if (isAbsent(value)) return [] + return isStringArray(value) ? value : null +} + +function parseDocOpFailure(value: unknown): DocOpFailure | null { + const failure = parseWireData(value) + if ( + failure === null || + !isSequence(failure.index) || + (!isAbsent(failure.op_id) && + (typeof failure.op_id !== 'string' || + !hasBoundedUtf8Length(failure.op_id, MAX_OP_ID_LENGTH))) || + typeof failure.code !== 'string' || + !hasBoundedUtf8Length(failure.code, MAX_ERROR_CODE_LENGTH) || + typeof failure.message !== 'string' || + !hasBoundedUtf8Length(failure.message, MAX_ERROR_MESSAGE_LENGTH) + ) + return null + + return { + index: failure.index, + ...(!isAbsent(failure.op_id) && { op_id: failure.op_id }), + code: failure.code, + message: failure.message + } +} + +// Defence in depth behind the server's identical cap. The counts are not +// byte-identical: Go's json.Marshal HTML-escapes `<`, `>` and `&`, so the +// server always counts >= this and is the stricter of the two. +function encodedJsonSize(value: Record): number | null { try { - return new TextEncoder().encode(JSON.stringify(state)).byteLength <= - MAX_AWARENESS_STATE_BYTES - ? state - : null + const encoded = JSON.stringify(value) + if (encoded.length > MAX_AWARENESS_STATE_BYTES) return encoded.length + return utf8.encode(encoded).length } catch { return null } @@ -162,38 +264,49 @@ export function parseServerDocFrame(value: unknown): ServerDocFrame | null { if ( data === null || data.v !== DOC_PROTOCOL_VERSION || - typeof data.workflow_id !== 'string' + typeof data.workflow_id !== 'string' || + !isValidWorkflowId(data.workflow_id) ) return null if ( frame.type === 'doc_update' && - typeof data.seq === 'number' && + isSequence(data.seq) && typeof data.update_b64 === 'string' ) { + const update = decodeBase64(data.update_b64) + if (update === null) return null + if (!isAbsent(data.op_ids) && !isStringArray(data.op_ids)) return null + const actor = + typeof data.actor === 'string' && isValidActor(data.actor) + ? data.actor + : undefined return { type: frame.type, data: { workflowId: data.workflow_id, seq: data.seq, - update: decodeBase64(data.update_b64), - ...(typeof data.actor === 'string' && { actor: data.actor }), + update, + ...(actor !== undefined && { actor }), ...(Array.isArray(data.op_ids) && { - opIds: data.op_ids.filter( - (item): item is string => typeof item === 'string' - ) + opIds: data.op_ids }) } } } if (frame.type === 'doc_subscribed' && typeof data.ok === 'boolean') { + if ( + (!isAbsent(data.seq) && !isSequence(data.seq)) || + !hasValidDiagnostics(data) + ) + return null return { type: frame.type, data: { workflowId: data.workflow_id, ok: data.ok, - ...(typeof data.seq === 'number' && { seq: data.seq }), + ...(isSequence(data.seq) && { seq: data.seq }), ...(typeof data.code === 'string' && { code: data.code }), ...(typeof data.message === 'string' && { message: data.message }) } @@ -201,56 +314,67 @@ export function parseServerDocFrame(value: unknown): ServerDocFrame | null { } if (frame.type === 'doc_ops_result' && typeof data.ok === 'boolean') { + const applied = parseOptionalStringArray(data.applied) + const skipped = parseOptionalStringArray(data.skipped) + if (applied === null || skipped === null) return null + if ( + (!isAbsent(data.seq) && !isSequence(data.seq)) || + !hasValidDiagnostics(data) + ) + return null + let failed: DocOpFailure | undefined + if (!isAbsent(data.failed)) { + const parsedFailure = parseDocOpFailure(data.failed) + if (parsedFailure === null) return null + failed = parsedFailure + } return { type: frame.type, data: { workflowId: data.workflow_id, ok: data.ok, - applied: Array.isArray(data.applied) - ? data.applied.filter( - (item): item is string => typeof item === 'string' - ) - : [], - skipped: Array.isArray(data.skipped) - ? data.skipped.filter( - (item): item is string => typeof item === 'string' - ) - : [], - ...(typeof data.seq === 'number' && { seq: data.seq }), + applied, + skipped, + ...(isSequence(data.seq) && { seq: data.seq }), ...(typeof data.code === 'string' && { code: data.code }), ...(typeof data.message === 'string' && { message: data.message }), - // PoC diagnostics: surface the failure verbatim (object, not array). - ...(data.failed != null && { failed: data.failed }) + ...(failed !== undefined && { failed }) } } } - if (frame.type === 'doc_reset' && typeof data.seq === 'number') { + if (frame.type === 'doc_reset' && isSequence(data.seq)) { + const actor = + typeof data.actor === 'string' && isValidActor(data.actor) + ? data.actor + : undefined return { type: frame.type, data: { workflowId: data.workflow_id, seq: data.seq, - ...(typeof data.actor === 'string' && { actor: data.actor }) + ...(actor !== undefined && { actor }) } } } if (frame.type === 'awareness' && typeof data.actor === 'string') { - const state = parseAwarenessState(data.state) - if ( - state === null || - (data.expires_at !== undefined && !isNonNegativeInteger(data.expires_at)) - ) - return null - + if (!isValidActor(data.actor)) return null + const state = parseRecord(data.state) + if (!isAbsent(data.state) && state === null) return null + if (state !== null) { + const stateSize = encodedJsonSize(state) + if (stateSize === null || stateSize > MAX_AWARENESS_STATE_BYTES) + return null + } + if (!isAbsent(data.expires_at) && !isSequence(data.expires_at)) return null return { type: frame.type, data: { workflowId: data.workflow_id, actor: data.actor, - ...(state !== undefined && { state }), - ...(data.expires_at !== undefined && { + ...(state !== null && { state }), + ...(isSequence(data.expires_at) && { expiresAt: data.expires_at }) } @@ -265,6 +389,7 @@ export class DocFrameClient extends EventTarget { constructor(private readonly transport: DocFrameTransport) { super() + const reportedTypes = new Set() for (const type of [ 'doc_update', 'doc_subscribed', @@ -275,8 +400,17 @@ export class DocFrameClient extends EventTarget { const listener: EventListener = (event) => { if (!(event instanceof CustomEvent)) return const parsed = parseServerDocFrame({ type, data: event.detail }) - if (parsed) + if (parsed) { this.dispatchEvent(new CustomEvent(type, { detail: parsed.data })) + return + } + if (reportedTypes.has(type)) return + reportedTypes.add(type) + reportError(new Error('Discarded invalid server document frame'), { + errorType: 'agent_crdt_invalid_server_frame', + tags: { frame_type: type }, + level: 'warning' + }) } this.listeners.set(type, listener) transport.addEventListener(type, listener) diff --git a/src/workbench/extensions/agent/crdt/followerSubscription.test.ts b/src/workbench/extensions/agent/crdt/followerSubscription.test.ts index fa91a342da6..3c9947a34c6 100644 --- a/src/workbench/extensions/agent/crdt/followerSubscription.test.ts +++ b/src/workbench/extensions/agent/crdt/followerSubscription.test.ts @@ -736,7 +736,8 @@ describe('FE-GAP-1 — a seq jump means a dropped frame and forces a resync', () v: 1, workflow_id: WORKFLOW_ID, ok: false, - code: 'not_found' + code: 'not_found', + message: 'workflow not found' }) expect(bridge.subscribedWorkflowId).toBeNull()