@devicerail/live-visualizer 0.1.0

package/dist/presentation.js

@@ -0,0 +1,341 @@
+import { LiveTimelineError } from "./errors.js";
+import { boundedJson, boundedText, deepFreeze } from "./sanitize.js";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+function record(value, location) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new LiveTimelineError("invalid_event", `${location} must be an object`);
+    }
+    return value;
+}
+function stringValue(value, location) {
+    if (typeof value !== "string") {
+        throw new LiveTimelineError("invalid_event", `${location} must be a string`);
+    }
+    return value;
+}
+function uuid(value, location) {
+    const text = stringValue(value, location);
+    if (!UUID_PATTERN.test(text)) {
+        throw new LiveTimelineError("invalid_event", `${location} must be a UUID`);
+    }
+    return text;
+}
+function safeInteger(value, location, minimum = 0) {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new LiveTimelineError("invalid_event", `${location} must be a safe integer`);
+    }
+    return value;
+}
+function finiteNumber(value, location) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new LiveTimelineError("invalid_event", `${location} must be finite`);
+    }
+    return value;
+}
+function evidence(asset, limits) {
+    const value = record(asset, "Evidence");
+    // URI is validated as a wire field, then deliberately discarded. It must
+    // never cross the live presentation boundary.
+    stringValue(value.uri, "Evidence.uri");
+    const sha256 = value.sha256;
+    return deepFreeze({
+        availability: "referenceOnly",
+        id: boundedText(stringValue(value.id, "Evidence.id"), limits.maxTextBytes),
+        mediaType: boundedText(stringValue(value.mediaType, "Evidence.mediaType"), limits.maxTextBytes),
+        ...(sha256 === undefined || sha256 === null
+            ? {}
+            : { sha256: boundedText(stringValue(sha256, "Evidence.sha256"), limits.maxTextBytes) }),
+    });
+}
+function evidenceList(value, limits, location) {
+    if (value === undefined)
+        return Object.freeze({ evidence: Object.freeze([]), omitted: 0 });
+    if (!Array.isArray(value)) {
+        throw new LiveTimelineError("invalid_event", `${location} must be an array`);
+    }
+    const kept = value.slice(0, limits.maxEvidencePerEvent).map((asset) => evidence(asset, limits));
+    return Object.freeze({
+        evidence: Object.freeze(kept),
+        omitted: Math.max(0, value.length - kept.length),
+    });
+}
+function observation(value, limits) {
+    const source = record(value, "Observation");
+    const viewport = record(source.viewport, "Observation.viewport");
+    const screenshotOmission = source.screenshotOmission;
+    if (screenshotOmission !== undefined &&
+        screenshotOmission !== null &&
+        screenshotOmission !== "policy" &&
+        screenshotOmission !== "protectedAction") {
+        throw new LiveTimelineError("invalid_event", "Observation.screenshotOmission is invalid");
+    }
+    if (screenshotOmission && source.screenshot !== undefined && source.screenshot !== null) {
+        throw new LiveTimelineError("invalid_event", "an omitted Observation cannot also expose screenshot Evidence");
+    }
+    const width = safeInteger(viewport.width, "Observation.viewport.width");
+    const height = safeInteger(viewport.height, "Observation.viewport.height");
+    if (width > 0xffff_ffff || height > 0xffff_ffff) {
+        throw new LiveTimelineError("invalid_event", "Observation viewport exceeds u32");
+    }
+    return deepFreeze({
+        capturedAtMs: safeInteger(source.capturedAtMs, "Observation.capturedAtMs"),
+        deviceId: boundedText(stringValue(source.deviceId, "Observation.deviceId"), limits.maxTextBytes),
+        id: boundedText(uuid(source.id, "Observation.id"), limits.maxTextBytes),
+        ...(source.screenshot === undefined || source.screenshot === null
+            ? {}
+            : { screenshot: evidence(source.screenshot, limits) }),
+        ...(screenshotOmission ? { screenshotOmission } : {}),
+        viewport: {
+            height,
+            scaleFactor: finiteNumber(viewport.scaleFactor, "Observation.viewport.scaleFactor"),
+            width,
+        },
+    });
+}
+function errorInfo(value, limits) {
+    const source = record(value, "ErrorInfo");
+    if (typeof source.retryable !== "boolean") {
+        throw new LiveTimelineError("invalid_event", "ErrorInfo.retryable must be boolean");
+    }
+    return deepFreeze({
+        code: boundedText(stringValue(source.code, "ErrorInfo.code"), limits.maxTextBytes),
+        ...(source.details === undefined || source.details === null
+            ? {}
+            : { details: boundedJson(source.details, limits) }),
+        message: boundedText(stringValue(source.message, "ErrorInfo.message"), limits.maxTextBytes),
+        retryable: source.retryable,
+    });
+}
+function completion(value, limits) {
+    const source = record(value, "Action outcome");
+    switch (source.outcome) {
+        case "succeeded": {
+            const result = record(source.result, "Action result");
+            uuid(result.callId, "Action result.callId");
+            if (!Object.hasOwn(result, "output")) {
+                throw new LiveTimelineError("invalid_event", "Action result.output is required");
+            }
+            const references = evidenceList(result.evidence, limits, "Action result.evidence");
+            return deepFreeze({
+                outcome: "succeeded",
+                ...(result.after === undefined || result.after === null
+                    ? {}
+                    : { after: observation(result.after, limits) }),
+                ...(result.before === undefined || result.before === null
+                    ? {}
+                    : { before: observation(result.before, limits) }),
+                evidence: references.evidence,
+                evidenceOmitted: references.omitted,
+                finishedAtMs: safeInteger(result.finishedAtMs, "Action result.finishedAtMs"),
+                output: boundedJson(result.output, limits),
+                startedAtMs: safeInteger(result.startedAtMs, "Action result.startedAtMs"),
+            });
+        }
+        case "failed":
+        case "cancelled":
+            return deepFreeze({
+                outcome: source.outcome,
+                error: errorInfo(source.error, limits),
+            });
+        case "timedOut":
+            return deepFreeze({
+                outcome: "timedOut",
+                error: errorInfo(source.error, limits),
+                timeoutMs: safeInteger(source.timeoutMs, "Action timeoutMs"),
+            });
+        default:
+            throw new LiveTimelineError("invalid_event", "Action outcome is unknown");
+    }
+}
+function actionStarted(value, limits) {
+    const source = record(value, "RecordedActionCall");
+    if (source.argumentsRedacted !== undefined && typeof source.argumentsRedacted !== "boolean") {
+        throw new LiveTimelineError("invalid_event", "RecordedActionCall.argumentsRedacted must be boolean");
+    }
+    return deepFreeze({
+        type: "actionStarted",
+        arguments: source.argumentsRedacted === true
+            ? { omitted: "protected" }
+            : boundedJson(source.arguments ?? null, limits),
+        callId: boundedText(uuid(source.id, "RecordedActionCall.id"), limits.maxTextBytes),
+        name: boundedText(stringValue(source.name, "RecordedActionCall.name"), limits.maxTextBytes),
+    });
+}
+function verdict(value, limits) {
+    const source = record(value, "Verdict");
+    if (source.status !== "pass" && source.status !== "fail" && source.status !== "unknown") {
+        throw new LiveTimelineError("invalid_event", "Verdict.status is invalid");
+    }
+    const references = evidenceList(source.evidence, limits, "Verdict.evidence");
+    return deepFreeze({
+        type: "verdictRecorded",
+        status: source.status,
+        summary: boundedText(stringValue(source.summary, "Verdict.summary"), limits.maxTextBytes),
+        evidence: references.evidence,
+        evidenceOmitted: references.omitted,
+    });
+}
+export function presentEvent(event, limits) {
+    const source = record(event, "TestEvent");
+    const payload = record(source.payload, "TestEvent.payload");
+    const sessionId = uuid(source.sessionId, "TestEvent.sessionId");
+    const common = {
+        atMs: safeInteger(source.atMs, "TestEvent.atMs"),
+        ...(source.deviceId === undefined || source.deviceId === null
+            ? {}
+            : {
+                deviceId: boundedText(stringValue(source.deviceId, "TestEvent.deviceId"), limits.maxTextBytes),
+            }),
+        eventId: boundedText(uuid(source.eventId, "TestEvent.eventId"), limits.maxTextBytes),
+        sequence: safeInteger(source.sequence, "TestEvent.sequence", 1),
+        sessionId,
+    };
+    let category;
+    let title;
+    let status;
+    let presentation;
+    switch (payload.type) {
+        case "sessionStarted":
+            category = "session";
+            title = "Session started";
+            presentation = { type: "sessionStarted" };
+            break;
+        case "sessionEnded":
+            if (payload.outcome !== "completed" &&
+                payload.outcome !== "failed" &&
+                payload.outcome !== "cancelled" &&
+                payload.outcome !== "shutdown") {
+                throw new LiveTimelineError("invalid_event", "Session outcome is invalid");
+            }
+            category = "session";
+            title = "Session ended";
+            status = payload.outcome[0]?.toUpperCase() + payload.outcome.slice(1);
+            presentation = deepFreeze({
+                type: "sessionEnded",
+                outcome: payload.outcome,
+                ...(payload.reason === undefined || payload.reason === null
+                    ? {}
+                    : {
+                        reason: boundedText(stringValue(payload.reason, "Session end reason"), limits.maxTextBytes),
+                    }),
+            });
+            break;
+        case "observationCaptured":
+            category = "observation";
+            title = "Observation captured";
+            presentation = deepFreeze({
+                type: "observationCaptured",
+                observation: observation(payload.observation, limits),
+            });
+            break;
+        case "actionStarted":
+            category = "action";
+            title = "Action started";
+            presentation = actionStarted(payload.call, limits);
+            break;
+        case "actionCompleted": {
+            category = "action";
+            title = "Action completed";
+            const callId = uuid(payload.callId, "Action callId");
+            const outcomeSource = record(payload.outcome, "Action outcome");
+            if (outcomeSource.outcome === "succeeded") {
+                const result = record(outcomeSource.result, "Action result");
+                if (uuid(result.callId, "Action result.callId") !== callId) {
+                    throw new LiveTimelineError("invalid_event", "Action result callId does not match its completed event");
+                }
+            }
+            const completed = completion(payload.outcome, limits);
+            status =
+                completed.outcome === "timedOut"
+                    ? "Timed out"
+                    : completed.outcome[0]?.toUpperCase() + completed.outcome.slice(1);
+            presentation = deepFreeze({
+                type: "actionCompleted",
+                callId: boundedText(callId, limits.maxTextBytes),
+                completion: completed,
+            });
+            break;
+        }
+        case "mediaStreamStarted": {
+            const stream = record(payload.stream, "Media stream");
+            const streamId = uuid(stream.id, "Media stream.id");
+            const kind = stringValue(stream.kind, "Media stream.kind");
+            if (kind !== "screenshot" && kind !== "video") {
+                throw new LiveTimelineError("invalid_event", "Media stream.kind is invalid");
+            }
+            let viewport;
+            if (stream.viewport !== undefined && stream.viewport !== null) {
+                const sourceViewport = record(stream.viewport, "Media stream.viewport");
+                const width = safeInteger(sourceViewport.width, "Media stream.viewport.width", 1);
+                const height = safeInteger(sourceViewport.height, "Media stream.viewport.height", 1);
+                const scaleFactor = finiteNumber(sourceViewport.scaleFactor, "Media stream.viewport.scaleFactor");
+                if (width > 0xffff_ffff || height > 0xffff_ffff || scaleFactor <= 0) {
+                    throw new LiveTimelineError("invalid_event", "Media stream viewport is invalid");
+                }
+                viewport = Object.freeze({ height, scaleFactor, width });
+            }
+            category = "media";
+            title = "Media stream started";
+            presentation = deepFreeze({
+                type: "mediaStreamStarted",
+                streamId: boundedText(streamId, limits.maxTextBytes),
+                kind,
+                mediaType: boundedText(stringValue(stream.mediaType, "Media stream.mediaType"), limits.maxTextBytes),
+                ...(viewport === undefined ? {} : { viewport }),
+            });
+            break;
+        }
+        case "mediaFrameCaptured": {
+            const frame = record(payload.frame, "Media frame");
+            category = "media";
+            title = "Media frame captured";
+            presentation = deepFreeze({
+                type: "mediaFrameCaptured",
+                streamId: boundedText(uuid(frame.streamId, "Media frame.streamId"), limits.maxTextBytes),
+                frameIndex: safeInteger(frame.frameIndex, "Media frame.frameIndex", 1),
+                keyFrame: frame.keyFrame === true,
+                ...(frame.durationMs === undefined || frame.durationMs === null
+                    ? {}
+                    : { durationMs: safeInteger(frame.durationMs, "Media frame.durationMs") }),
+                evidence: evidence(frame.evidence, limits),
+            });
+            break;
+        }
+        case "mediaStreamEnded":
+            category = "media";
+            title = "Media stream ended";
+            presentation = deepFreeze({
+                type: "mediaStreamEnded",
+                streamId: boundedText(uuid(payload.streamId, "Media stream terminal.streamId"), limits.maxTextBytes),
+                frameCount: safeInteger(payload.frameCount, "Media stream terminal.frameCount"),
+            });
+            break;
+        case "error":
+            category = "error";
+            title = "Error";
+            presentation = deepFreeze({
+                type: "error",
+                error: errorInfo(payload.error, limits),
+            });
+            break;
+        case "verdictRecorded": {
+            category = "verdict";
+            title = "Verdict recorded";
+            presentation = verdict(payload.verdict, limits);
+            if (presentation.type !== "verdictRecorded") {
+                throw new LiveTimelineError("invalid_event", "Verdict presentation is invalid");
+            }
+            status = presentation.status[0]?.toUpperCase() + presentation.status.slice(1);
+            break;
+        }
+        default:
+            throw new LiveTimelineError("invalid_event", "TestEvent payload type is unknown");
+    }
+    return deepFreeze({
+        ...common,
+        category,
+        presentation,
+        ...(status ? { status } : {}),
+        title,
+    });
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,8 @@
+import type { BoundedJson, BoundedText, LiveTimelineLimits } from "./types.js";
+export declare function boundedText(value: string, maxBytes: number): BoundedText;
+export declare function canonicalFingerprint(value: unknown, limits: LiveTimelineLimits): {
+    readonly canonical: string;
+    readonly fingerprint: string;
+};
+export declare function boundedJson(value: unknown, limits: LiveTimelineLimits): BoundedJson;
+export declare function deepFreeze<T>(value: T): T;

package/dist/sanitize.js

@@ -0,0 +1,261 @@
+import { createHash } from "node:crypto";
+import { LiveTimelineError } from "./errors.js";
+const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function escapeCodePoint(codePoint) {
+    return `\\u{${codePoint.toString(16).padStart(4, "0")}}`;
+}
+function escapedCharacter(character, codePoint) {
+    const isControl = codePoint <= 0x1f ||
+        (codePoint >= 0x7f && codePoint <= 0x9f) ||
+        (codePoint >= 0xd800 && codePoint <= 0xdfff);
+    const isBidi = codePoint === 0x061c ||
+        codePoint === 0x200e ||
+        codePoint === 0x200f ||
+        (codePoint >= 0x202a && codePoint <= 0x202e) ||
+        (codePoint >= 0x2066 && codePoint <= 0x2069);
+    const isMarkup = character === "<" || character === ">" || character === "&";
+    return isControl || isBidi || isMarkup ? escapeCodePoint(codePoint) : character;
+}
+export function boundedText(value, maxBytes) {
+    let text = "";
+    let bytes = 0;
+    let truncated = false;
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint === undefined)
+            continue;
+        const escaped = escapedCharacter(character, codePoint);
+        const addition = Buffer.byteLength(escaped);
+        if (bytes + addition > maxBytes) {
+            truncated = true;
+            break;
+        }
+        text += escaped;
+        bytes += addition;
+    }
+    return Object.freeze({ text, truncated });
+}
+class CanonicalWriter {
+    #blocks = [];
+    #limit;
+    #bytes = 0;
+    #pending = [];
+    #pendingBytes = 0;
+    constructor(limit) {
+        this.#limit = limit;
+    }
+    push(value) {
+        const bytes = Buffer.byteLength(value);
+        if (this.#bytes + bytes > this.#limit) {
+            throw new LiveTimelineError("viewer_capacity_exceeded", "input event exceeds the canonical fingerprint byte limit", { details: { limitBytes: this.#limit, observedBytesAtLeast: this.#bytes + bytes } });
+        }
+        if (this.#pendingBytes + bytes > 8 * 1024 || this.#pending.length >= 256) {
+            this.#flush();
+        }
+        this.#pending.push(value);
+        this.#pendingBytes += bytes;
+        this.#bytes += bytes;
+    }
+    finish() {
+        this.#flush();
+        return this.#blocks.join("");
+    }
+    #flush() {
+        if (this.#pending.length === 0)
+            return;
+        this.#blocks.push(this.#pending.join(""));
+        this.#pending = [];
+        this.#pendingBytes = 0;
+    }
+}
+function jsonEncode(value) {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined) {
+        throw new LiveTimelineError("invalid_event", "input event contains a non-JSON value");
+    }
+    return encoded;
+}
+function writeJsonString(value, writer) {
+    writer.push('"');
+    let plain = "";
+    const flushPlain = () => {
+        if (plain.length === 0)
+            return;
+        writer.push(plain);
+        plain = "";
+    };
+    for (const character of value) {
+        const encoded = jsonEncode(character).slice(1, -1);
+        if (encoded === character) {
+            plain += character;
+            if (plain.length >= 1_024)
+                flushPlain();
+        }
+        else {
+            flushPlain();
+            writer.push(encoded);
+        }
+    }
+    flushPlain();
+    writer.push('"');
+}
+function canonicalVisit(value, writer, depth, maxDepth, ancestors) {
+    if (depth > maxDepth) {
+        throw new LiveTimelineError("invalid_event", "input event exceeds the JSON depth limit", {
+            details: { maxDepth },
+        });
+    }
+    if (value === null || typeof value === "boolean") {
+        writer.push(String(value));
+        return;
+    }
+    if (typeof value === "string") {
+        writeJsonString(value, writer);
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))) {
+            throw new LiveTimelineError("invalid_event", "input event contains an unsafe number");
+        }
+        writer.push(jsonEncode(value));
+        return;
+    }
+    if (typeof value !== "object") {
+        throw new LiveTimelineError("invalid_event", "input event contains a non-JSON value");
+    }
+    const prototype = Object.getPrototypeOf(value);
+    const isArray = Array.isArray(value);
+    if ((isArray && prototype !== Array.prototype) ||
+        (!isArray && prototype !== Object.prototype && prototype !== null)) {
+        throw new LiveTimelineError("invalid_event", "input event contains a non-JSON prototype");
+    }
+    if (ancestors.has(value)) {
+        throw new LiveTimelineError("invalid_event", "input event contains a cycle");
+    }
+    ancestors.add(value);
+    if (isArray) {
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new LiveTimelineError("invalid_event", "input event contains symbol keys");
+        }
+        writer.push("[");
+        for (let index = 0; index < value.length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor) {
+                throw new LiveTimelineError("invalid_event", "input event contains a sparse array");
+            }
+            if (!("value" in descriptor) || !descriptor.enumerable) {
+                throw new LiveTimelineError("invalid_event", "input event contains array accessors");
+            }
+            if (index > 0)
+                writer.push(",");
+            canonicalVisit(descriptor.value, writer, depth + 1, maxDepth, ancestors);
+        }
+        writer.push("]");
+    }
+    else {
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new LiveTimelineError("invalid_event", "input event contains symbol keys");
+        }
+        writer.push("{");
+        const record = value;
+        const keys = Object.keys(record).sort();
+        keys.forEach((key, index) => {
+            if (index > 0)
+                writer.push(",");
+            writeJsonString(key, writer);
+            writer.push(":");
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !("value" in descriptor)) {
+                throw new LiveTimelineError("invalid_event", "input event contains an accessor or changed during fingerprinting");
+            }
+            canonicalVisit(descriptor.value, writer, depth + 1, maxDepth, ancestors);
+        });
+        writer.push("}");
+    }
+    ancestors.delete(value);
+}
+export function canonicalFingerprint(value, limits) {
+    const writer = new CanonicalWriter(limits.maxInputEventBytes);
+    canonicalVisit(value, writer, 0, limits.maxJsonDepth, new Set());
+    const canonical = writer.finish();
+    return Object.freeze({
+        canonical,
+        fingerprint: createHash("sha256").update(canonical, "utf8").digest("hex"),
+    });
+}
+function presentationValue(value, limits, depth, state) {
+    if (depth > limits.maxJsonDepth) {
+        state.truncated = true;
+        return "[depth limit]";
+    }
+    if (typeof value === "string") {
+        const text = boundedText(value, limits.maxTextBytes);
+        if (text.truncated)
+            state.truncated = true;
+        return text.text;
+    }
+    if (value === null || typeof value === "boolean" || typeof value === "number")
+        return value;
+    if (Array.isArray(value)) {
+        const count = Math.min(value.length, 128);
+        if (count < value.length)
+            state.truncated = true;
+        return value
+            .slice(0, count)
+            .map((child) => presentationValue(child, limits, depth + 1, state));
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+        const count = Math.min(entries.length, 128);
+        if (count < entries.length)
+            state.truncated = true;
+        const pairs = [];
+        const seen = new Set();
+        let collision = false;
+        for (const [rawKey, child] of entries.slice(0, count)) {
+            const labelled = DANGEROUS_KEYS.has(rawKey) ? `[unsafe-key:${rawKey}]` : rawKey;
+            const boundedKey = boundedText(labelled, limits.maxTextBytes);
+            if (boundedKey.truncated)
+                state.truncated = true;
+            if (seen.has(boundedKey.text))
+                collision = true;
+            seen.add(boundedKey.text);
+            pairs.push([
+                boundedKey.text,
+                presentationValue(child, limits, depth + 1, state),
+            ]);
+        }
+        if (collision) {
+            state.truncated = true;
+            const collisionSafe = Object.create(null);
+            collisionSafe["[collision-safe object entries]"] = pairs;
+            return collisionSafe;
+        }
+        const result = Object.create(null);
+        for (const [key, child] of pairs)
+            result[key] = child;
+        return result;
+    }
+    state.truncated = true;
+    return "[non-JSON value]";
+}
+export function boundedJson(value, limits) {
+    const state = { truncated: false };
+    const safe = presentationValue(value, limits, 0, state);
+    const json = jsonEncode(safe);
+    if (Buffer.byteLength(json) <= limits.maxJsonBytes) {
+        return Object.freeze({ json, truncated: state.truncated });
+    }
+    return Object.freeze({
+        json: jsonEncode(`[JSON exceeds ${limits.maxJsonBytes}-byte presentation limit]`),
+        truncated: true,
+    });
+}
+export function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}