UNPKG

quelda

Version:

PDF & Illustrator security scanner (WebAssembly): files + policy in, verdict out

621 lines (620 loc) • 24.6 kB
// Main-thread side of the scanner: input normalization, one worker running one // request at a time, timeouts / cancellation (kill the worker), and turning // every failure into an ERROR verdict (fail-closed). No scan logic: the WASM // engine in the worker does all of it. import { errorMessage } from './protocol.js'; import { STATUSES, } from './types.js'; /** Default per-request timeout (ms). */ export const DEFAULT_TIMEOUT_MS = 30_000; /** Longest delay `setTimeout` honours (larger values fire at once). */ const MAX_TIMER_MS = 2_147_483_647; /** Rejection reason of `createScanner` and `listRules`. */ export class QueldaError extends Error { code; constructor(code, message) { super(message); this.name = 'QueldaError'; this.code = code; } } /** A failure outside the engine (internal; never confused with DOMException & co). */ class Failure { code; message; constructor(code, message) { this.code = code; this.message = message; } } /** * A worker whose WASM memory grew past this after a scan is replaced * (memory is returned to the system). Scans of a `File` / `Blob` stay far * below; a large `ArrayBuffer` is copied into WASM memory whole. */ export const RECYCLE_MEMORY_BYTES = 64 * 1024 * 1024; const byteSize = (b) => (b instanceof ArrayBuffer ? b.byteLength : b.size); const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now()); const tag = (x) => Object.prototype.toString.call(x); function isDetached(buf) { return buf.detached === true; } /** * Moves the caller's buffer into a new one without copying, so it is detached * right when `scan` is called (not later, when a queued scan starts). */ function take(buf) { if (typeof structuredClone !== 'function') return buf; // detached when posted try { return structuredClone(buf, { transfer: [buf] }); } catch (e) { throw failure('ENGINE.INPUT', `could not transfer the buffer: ${errorMessage(e)}`); } } function failure(code, message) { return new Failure(code, message); } function isFailure(x) { return x instanceof Failure; } /** Validated timeout: `null` = none. Throws a Failure. */ export function resolveTimeout(value, fallback) { if (value === undefined) return fallback; if (value === Infinity) return null; if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) { throw failure('ENGINE.INPUT', `timeoutMs must be a positive number or Infinity, got ${String(value)}`); } return Math.min(value, MAX_TIMER_MS); } /** * Turns the input into an `ArrayBuffer` the scanner owns (safe to transfer) * — copied unless `transfer` is set and the buffer can be handed over whole — * or a `Blob` / `File` as is: the worker reads only the parts the engine * needs (plan Step 16 Phase B). Throws / rejects with a Failure. */ export async function normalizeInput(input, transfer) { const t = tag(input); if (t === '[object ArrayBuffer]') { const buf = input; if (isDetached(buf)) throw failure('ENGINE.INPUT', 'the ArrayBuffer is detached'); return transfer ? take(buf) : buf.slice(0); } if (t === '[object SharedArrayBuffer]') { return new Uint8Array(input).slice().buffer; } if (ArrayBuffer.isView(input)) { const buf = input.buffer; if (isDetached(buf)) throw failure('ENGINE.INPUT', 'the buffer of the view is detached'); if (transfer && tag(buf) === '[object ArrayBuffer]' && input.byteOffset === 0 && input.byteLength === buf.byteLength) { return take(buf); } return new Uint8Array(buf, input.byteOffset, input.byteLength).slice().buffer; } const isBlob = (typeof Blob !== 'undefined' && input instanceof Blob) || ((t === '[object Blob]' || t === '[object File]') && typeof input.arrayBuffer === 'function'); if (isBlob) return input; throw failure('ENGINE.INPUT', `unsupported input (${t}): expected File, Blob, ArrayBuffer or Uint8Array`); } /** Policy JSON for the engine (which validates it). Throws a Failure. */ export function policyJson(policy) { if (policy === undefined) return '{}'; if (typeof policy === 'string') return policy; let json; try { json = JSON.stringify(policy); } catch (e) { throw failure('POLICY.INVALID', `policy is not serializable to JSON: ${errorMessage(e)}`); } if (typeof json !== 'string') throw failure('POLICY.INVALID', 'policy is not serializable to JSON'); return json; } const isObject = (x) => typeof x === 'object' && x !== null && !Array.isArray(x); /** * Parses the engine's verdict JSON and checks its invariants (schema §7). * Fills `stats.duration_ms` (the WASM engine has no clock) with the * worker-measured engine time. Throws a Failure on anything unexpected. */ export function parseVerdict(text, durationMs) { const bad = (why) => failure('ENGINE.WORKER', `malformed verdict from the engine: ${why}`); if (typeof text !== 'string') throw bad('not a string'); let v; try { v = JSON.parse(text); } catch { throw bad('not JSON'); } if (!isObject(v)) throw bad('not an object'); const { valid, status, violations, warnings, errors, stats, policy, engine_version } = v; if (typeof status !== 'string' || !STATUSES.includes(status)) throw bad('status'); if (typeof valid !== 'boolean' || valid !== (status === 'PASS')) throw bad('valid does not match status'); if (!Array.isArray(violations) || !Array.isArray(warnings) || !Array.isArray(errors)) throw bad('lists'); if (status === 'PASS' && (violations.length > 0 || errors.length > 0)) throw bad('PASS with findings'); if (status === 'REJECT' && (violations.length === 0 || errors.length > 0)) throw bad('REJECT'); if (status === 'ERROR' && errors.length === 0) throw bad('ERROR without errors'); if (!isObject(stats) || typeof stats.duration_ms !== 'number') throw bad('stats'); if (!isObject(policy) || typeof engine_version !== 'string') throw bad('policy / engine_version'); if (stats.duration_ms === 0 && typeof durationMs === 'number' && Number.isFinite(durationMs) && durationMs > 0) { stats.duration_ms = Math.round(durationMs); } return v; } /** Parses the engine's rule list; throws a Failure if it is not one. */ export function parseRules(text) { const bad = failure('ENGINE.WORKER', 'malformed rule list from the engine'); if (typeof text !== 'string') throw bad; let v; try { v = JSON.parse(text); } catch { throw bad; } if (!Array.isArray(v) || !v.every((r) => isObject(r) && typeof r.id === 'string')) throw bad; return v; } /** An `ERROR` verdict for failures outside the engine. */ export function errorVerdict(f, engineVersion, bytes, durationMs) { return { valid: false, status: 'ERROR', violations: [], warnings: [], errors: [{ code: f.code, message: f.message }], engine_version: engineVersion, policy: { preset: null, digest: null, unsafe_allow_unlock: false, stop_on_first: false }, stats: { bytes, objects: 0, revisions: 0, decoded_bytes: 0, duration_ms: Math.max(0, Math.round(durationMs)), }, }; } function isSignal(x) { return (typeof x === 'object' && x !== null && typeof x.aborted === 'boolean' && typeof x.addEventListener === 'function' && typeof x.removeEventListener === 'function'); } function resolveWasm(wasm) { if (wasm === undefined) return undefined; if (typeof WebAssembly !== 'undefined' && wasm instanceof WebAssembly.Module) return wasm; if (wasm instanceof URL) return wasm.href; if (typeof wasm === 'string') { // Relative URLs would resolve against the worker script; use the page. const base = globalThis.location?.href; try { return base === undefined ? wasm : new URL(wasm, base).href; } catch { return wasm; } } throw new QueldaError('ENGINE.INPUT', 'wasm must be a URL, a string or a WebAssembly.Module'); } /** The scanner engine room. Use {@link createScannerWith}. */ class ScannerImpl { makeWorker; wasm; timeoutMs; engineVersion = ''; slot; queue = []; active; terminated = false; nextId = 1; rulesJson; constructor(makeWorker, wasm, timeoutMs) { this.makeWorker = makeWorker; this.wasm = wasm; this.timeoutMs = timeoutMs; } /** Starts the first worker; rejects with a QueldaError. */ async start() { let timer; try { const slot = this.spawn(); const timeout = new Promise((_, reject) => { if (this.timeoutMs !== null) { timer = setTimeout(() => reject(new QueldaError('LIMIT.TIMEOUT', `the engine did not start within ${this.timeoutMs} ms`)), this.timeoutMs); } }); await Promise.race([slot.ready, timeout]); } catch (e) { this.terminate(); if (e instanceof QueldaError) throw e; if (isFailure(e)) throw new QueldaError(e.code, e.message); throw new QueldaError('ENGINE.WORKER', `could not start the scanner: ${errorMessage(e)}`); } finally { if (timer !== undefined) clearTimeout(timer); } } scan(input, policy, options) { const started = now(); const size = () => { try { const x = input; const n = typeof x?.byteLength === 'number' ? x.byteLength : typeof x?.size === 'number' ? x.size : 0; return Number.isFinite(n) && n >= 0 ? n : 0; } catch { return 0; } }; return new Promise((resolve) => { const fail = (f, bytes) => resolve(errorVerdict(f, this.engineVersion, bytes, now() - started)); try { if (this.terminated) throw failure('ENGINE.ABORTED', 'the scanner was terminated'); if (options !== undefined && !isObject(options)) throw failure('ENGINE.INPUT', 'options must be an object'); const { timeoutMs, signal, transfer } = options ?? {}; if (transfer !== undefined && typeof transfer !== 'boolean') { throw failure('ENGINE.INPUT', 'transfer must be a boolean'); } if (signal !== undefined && !isSignal(signal)) throw failure('ENGINE.INPUT', 'signal must be an AbortSignal'); const timeout = resolveTimeout(timeoutMs, this.timeoutMs); const json = policyJson(policy); if (signal?.aborted) throw failure('ENGINE.ABORTED', 'the scan was aborted'); const bytes = size(); // Normalize now: copies snapshot the caller's bytes at call time. const payload = normalizeInput(input, transfer === true).then((buf) => ({ bytes: buf, policy: json })); payload.catch(() => undefined); const job = { id: this.nextId++, kind: 'scan', phase: 'queued', done: false, timeoutMs: timeout, payload, bytes, started, settle: (o) => { if (o.ok) resolve(o.verdict); else fail(o.failure, job.bytes); }, }; this.enqueue(job, signal); } catch (e) { fail(isFailure(e) ? e : failure('ENGINE.INPUT', errorMessage(e)), size()); } }); } listRules(options) { return new Promise((resolve, reject) => { const fail = (f) => reject(new QueldaError(f.code, f.message)); try { if (this.terminated) throw failure('ENGINE.ABORTED', 'the scanner was terminated'); if (options !== undefined && !isObject(options)) throw failure('ENGINE.INPUT', 'options must be an object'); const { timeoutMs, signal } = options ?? {}; if (signal !== undefined && !isSignal(signal)) throw failure('ENGINE.INPUT', 'signal must be an AbortSignal'); const timeout = resolveTimeout(timeoutMs, this.timeoutMs); if (signal?.aborted) throw failure('ENGINE.ABORTED', 'listRules was aborted'); if (this.rulesJson !== undefined) { resolve(parseRules(this.rulesJson)); // fresh objects every call return; } const job = { id: this.nextId++, kind: 'rules', phase: 'queued', done: false, timeoutMs: timeout, bytes: 0, started: now(), settle: (o) => (o.ok ? resolve(o.rules) : fail(o.failure)), }; this.enqueue(job, signal); } catch (e) { fail(isFailure(e) ? e : failure('ENGINE.INPUT', errorMessage(e))); } }); } terminate() { if (this.terminated) return; this.terminated = true; this.killWorker(new Error('the scanner was terminated')); const pending = [...(this.active ? [this.active] : []), ...this.queue]; this.queue.length = 0; for (const job of pending) this.finish(job, { ok: false, failure: failure('ENGINE.ABORTED', 'the scanner was terminated') }); } // ---- queue ------------------------------------------------------------- enqueue(job, signal) { if (signal !== undefined) { const onAbort = () => this.abort(job); signal.addEventListener('abort', onAbort, { once: true }); job.unlisten = () => signal.removeEventListener('abort', onAbort); } this.queue.push(job); this.pump(); } /** Settles a job once; frees its timer/listener and moves the queue on. */ finish(job, outcome) { if (job.done) return; job.done = true; if (job.timer !== undefined) clearTimeout(job.timer); job.unlisten?.(); job.unlisten = undefined; job.payload = undefined; // drop the bytes const i = this.queue.indexOf(job); if (i >= 0) this.queue.splice(i, 1); if (this.active === job) this.active = undefined; job.settle(outcome); this.pump(); } abort(job) { if (job.done) return; // Only a running request occupies the engine; WASM cannot be interrupted. if (job.phase === 'running') this.killWorker(new Error('request aborted')); this.finish(job, { ok: false, failure: failure('ENGINE.ABORTED', `the ${job.kind === 'scan' ? 'scan' : 'request'} was aborted`) }); } onTimeout(job) { if (job.done) return; // A request stuck in the engine or in worker start-up: kill that worker. if (job.phase === 'running' || job.phase === 'starting') this.killWorker(new Error('request timed out')); this.finish(job, { ok: false, failure: failure('LIMIT.TIMEOUT', `the ${job.kind === 'scan' ? 'scan' : 'request'} took longer than ${job.timeoutMs} ms`) }); } pump() { if (this.active !== undefined || this.terminated) return; const job = this.queue.shift(); if (job === undefined) return; this.active = job; job.phase = 'preparing'; if (job.timeoutMs !== null) job.timer = setTimeout(() => this.onTimeout(job), job.timeoutMs); void this.run(job); } async run(job) { try { const payload = job.payload === undefined ? undefined : await job.payload; if (job.done) return; if (payload !== undefined) job.bytes = byteSize(payload.bytes); job.phase = 'starting'; const slot = this.slot ?? this.spawn(); await slot.ready; if (job.done) return; if (slot.dead || slot !== this.slot) throw failure('ENGINE.WORKER', 'the worker stopped'); job.phase = 'running'; job.slot = slot; if (job.kind === 'scan' && payload !== undefined) { const { bytes, policy } = payload; if (bytes instanceof ArrayBuffer) { slot.worker.postMessage({ type: 'scan', id: job.id, bytes, policy }, [bytes]); } else { slot.worker.postMessage({ type: 'scan', id: job.id, blob: bytes, policy }, []); } } else { slot.worker.postMessage({ type: 'rules', id: job.id }, []); } } catch (e) { if (job.done) return; // Start-up / posting failures leave no usable worker. if (job.phase === 'starting' || job.phase === 'running') this.killWorker(new Error('worker failure')); this.finish(job, { ok: false, failure: isFailure(e) ? e : failure('ENGINE.WORKER', `the worker failed: ${errorMessage(e)}`), }); } } // ---- worker ------------------------------------------------------------ spawn() { if (this.terminated) throw failure('ENGINE.ABORTED', 'the scanner was terminated'); let resolveReady; let rejectReady; const ready = new Promise((res, rej) => { resolveReady = res; rejectReady = rej; }); ready.catch(() => undefined); // observed by run()/start(); never unhandled let worker; try { worker = this.makeWorker(); } catch (e) { throw failure('ENGINE.WORKER', `could not create the worker: ${errorMessage(e)}`); } const onMessage = (e) => this.onMessage(slot, e.data); const onError = (e) => this.onWorkerDied(slot, `the worker crashed${typeof e?.message === 'string' && e.message ? `: ${e.message}` : ''}`); const onMessageError = () => this.onWorkerDied(slot, 'the worker sent a message that could not be read'); const slot = { worker, ready, dead: false, onReady: resolveReady, onDead: rejectReady, detach: () => { worker.removeEventListener('message', onMessage); worker.removeEventListener('error', onError); worker.removeEventListener('messageerror', onMessageError); }, }; worker.addEventListener('message', onMessage); worker.addEventListener('error', onError); worker.addEventListener('messageerror', onMessageError); this.slot = slot; try { worker.postMessage({ type: 'init', wasm: this.wasm }, []); } catch (e) { this.killWorker(new Error(`could not start the worker: ${errorMessage(e)}`)); } return slot; } /** Stops the current worker (if any); it is never reused. */ killWorker(reason) { const slot = this.slot; if (slot === undefined) return; this.slot = undefined; slot.dead = true; slot.detach(); try { slot.worker.terminate(); } catch { // already gone } slot.onDead(reason); } onWorkerDied(slot, message) { if (slot !== this.slot) return; this.killWorker(new Error(message)); const job = this.active; // A job waiting for this worker's start-up fails through `ready` in run(). if (job !== undefined && job.phase === 'running' && job.slot === slot) { this.finish(job, { ok: false, failure: failure('ENGINE.WORKER', message) }); } } onMessage(slot, data) { if (slot !== this.slot) return; const msg = (isObject(data) ? data : {}); if (msg.type === 'ready') { if (typeof msg.version !== 'string') return this.onWorkerDied(slot, 'the worker sent a malformed message'); if (this.engineVersion === '') this.engineVersion = msg.version; slot.onReady(); return; } if (msg.type === 'init-error') { return this.onWorkerDied(slot, typeof msg.message === 'string' ? msg.message : 'the engine failed to load'); } const job = this.active; if (job === undefined || job.phase !== 'running' || job.slot !== slot || msg.id !== job.id) { return this.onWorkerDied(slot, 'the worker sent an unexpected message'); } try { if (msg.type === 'fail') { // The engine threw or trapped: do not trust this instance again. throw failure('ENGINE.WORKER', typeof msg.message === 'string' ? msg.message : 'the engine failed'); } if (job.kind === 'scan' && msg.type === 'scan') { const verdict = parseVerdict(msg.verdict, msg.durationMs); // WASM memory never shrinks: hand it back to the system by starting // the next request in a fresh worker. if (typeof msg.memory === 'number' && msg.memory > RECYCLE_MEMORY_BYTES) { this.killWorker(new Error('worker recycled')); } this.finish(job, { ok: true, verdict }); return; } if (job.kind === 'scan' && msg.type === 'input-error') { const message = typeof msg.message === 'string' ? msg.message : 'could not read the file'; this.finish(job, { ok: false, failure: failure('ENGINE.INPUT', message) }); return; } if (job.kind === 'rules' && msg.type === 'rules') { const rules = parseRules(msg.rules); this.rulesJson = msg.rules; this.finish(job, { ok: true, rules }); return; } throw failure('ENGINE.WORKER', 'the worker sent an unexpected message'); } catch (e) { this.killWorker(new Error('bad reply')); this.finish(job, { ok: false, failure: isFailure(e) ? e : failure('ENGINE.WORKER', errorMessage(e)) }); } } } /** * Creates a scanner with an explicit worker factory and waits until its * engine is loaded. Rejects with a {@link QueldaError}. */ export async function createScannerWith(makeWorker, options = {}) { if (!isObject(options)) throw new QueldaError('ENGINE.INPUT', 'options must be an object'); const opts = options; let timeout; try { timeout = resolveTimeout(opts.timeoutMs, DEFAULT_TIMEOUT_MS); } catch (e) { throw new QueldaError('ENGINE.INPUT', isFailure(e) ? e.message : errorMessage(e)); } if (opts.worker !== undefined && typeof opts.worker !== 'function') { throw new QueldaError('ENGINE.INPUT', 'worker must be a function'); } const impl = new ScannerImpl(opts.worker ?? makeWorker, resolveWasm(opts.wasm), timeout); await impl.start(); // Expose only the public surface. return Object.freeze({ get engineVersion() { return impl.engineVersion; }, scan: impl.scan.bind(impl), listRules: impl.listRules.bind(impl), terminate: impl.terminate.bind(impl), }); }