quelda
Version:
PDF & Illustrator security scanner (WebAssembly): files + policy in, verdict out
99 lines (98 loc) • 4.66 kB
TypeScript
import { type WorkerLike } from './protocol.js';
import { type PolicyInput, type RuleInfo, type ScanInput, type ScannerErrorCode, type Verdict } from './types.js';
/** Default per-request timeout (ms). */
export declare const DEFAULT_TIMEOUT_MS = 30000;
export interface ScannerOptions {
/**
* Per request (scan, listRules, worker start-up) in ms; default 30 000.
* `Infinity` disables it. On timeout the worker is killed and the scan
* gives an `ERROR` verdict (`LIMIT.TIMEOUT`).
*/
timeoutMs?: number;
/**
* Where the worker loads the engine from: a URL (resolved against the
* page) or a compiled `WebAssembly.Module`. Default: the `.wasm` file
* shipped next to the worker, located by your bundler.
*/
wasm?: string | URL | WebAssembly.Module;
/**
* Advanced: creates the worker (e.g. under a strict CSP or when the package
* is served from another origin). It must run this package's `worker.js`.
*/
worker?: () => WorkerLike;
}
export interface ScanOptions {
/** Overrides the scanner's `timeoutMs` for this scan. */
timeoutMs?: number;
/** Aborting gives an `ERROR` verdict (`ENGINE.ABORTED`). */
signal?: AbortSignal;
/**
* `true`: hand the caller's `ArrayBuffer` (or the buffer of a `Uint8Array`
* that spans it whole) to the worker without copying. The caller's buffer
* is detached (length 0) afterwards. Default `false`: the bytes are copied
* when `scan` is called and the caller's buffer is untouched.
*/
transfer?: boolean;
}
export interface ListRulesOptions {
timeoutMs?: number;
signal?: AbortSignal;
}
export interface Scanner {
/** Engine version (`engine_version` in verdicts). */
readonly engineVersion: string;
/**
* Scans one file. Never rejects: anything that goes wrong (bad input,
* timeout, abort, worker crash, `terminate()`) gives a verdict with
* `status: "ERROR"` and `valid: false`.
*/
scan(input: ScanInput, policy?: PolicyInput, options?: ScanOptions): Promise<Verdict>;
/** Every rule the engine knows, sorted by ID. Rejects with a {@link QueldaError}. */
listRules(options?: ListRulesOptions): Promise<RuleInfo[]>;
/** Kills the worker. Pending scans give `ERROR` verdicts; later calls fail. Idempotent. */
terminate(): void;
}
/** Rejection reason of `createScanner` and `listRules`. */
export declare class QueldaError extends Error {
readonly code: ScannerErrorCode;
constructor(code: ScannerErrorCode, message: string);
}
/** A failure outside the engine (internal; never confused with DOMException & co). */
declare class Failure {
readonly code: ScannerErrorCode;
readonly message: string;
constructor(code: ScannerErrorCode, message: string);
}
/**
* 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 declare const RECYCLE_MEMORY_BYTES: number;
/** Validated timeout: `null` = none. Throws a Failure. */
export declare function resolveTimeout(value: unknown, fallback: number | null): number | null;
/**
* 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 declare function normalizeInput(input: unknown, transfer: boolean): Promise<ArrayBuffer | Blob>;
/** Policy JSON for the engine (which validates it). Throws a Failure. */
export declare function policyJson(policy: unknown): string;
/**
* 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 declare function parseVerdict(text: unknown, durationMs: unknown): Verdict;
/** Parses the engine's rule list; throws a Failure if it is not one. */
export declare function parseRules(text: unknown): RuleInfo[];
/** An `ERROR` verdict for failures outside the engine. */
export declare function errorVerdict(f: Failure, engineVersion: string, bytes: number, durationMs: number): Verdict;
/**
* Creates a scanner with an explicit worker factory and waits until its
* engine is loaded. Rejects with a {@link QueldaError}.
*/
export declare function createScannerWith(makeWorker: () => WorkerLike, options?: ScannerOptions): Promise<Scanner>;
export {};