quelda
Version:
PDF & Illustrator security scanner (WebAssembly): files + policy in, verdict out
621 lines (620 loc) • 24.6 kB
JavaScript
// 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),
});
}