swf-toolkit 0.0.0-stage → 0.1.0

package/dist/cjs/abc/analysis.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multinameRuntimeArity = multinameRuntimeArity;
+exports.stackEffect = stackEffect;
+exports.registersUsed = registersUsed;
+exports.computeLimits = computeLimits;
+exports.minLocalCount = minLocalCount;
+exports.verifyCode = verifyCode;
+const constants_js_1 = require("./constants.js");
+const opcodes_js_1 = require("./opcodes.js");
+/** Number of values a multiname pops from the stack at runtime (namespace and/or name). */
+function multinameRuntimeArity(abc, mnIndex) {
+    const m = abc.multinames[mnIndex];
+    if (!m)
+        return 0;
+    switch (m.kind) {
+        case constants_js_1.MultinameKind.RTQName:
+        case constants_js_1.MultinameKind.RTQNameA:
+        case constants_js_1.MultinameKind.MultinameL:
+        case constants_js_1.MultinameKind.MultinameLA:
+            return 1;
+        case constants_js_1.MultinameKind.RTQNameL:
+        case constants_js_1.MultinameKind.RTQNameLA:
+            return 2;
+        default:
+            return 0;
+    }
+}
+/** Values popped / pushed by an instruction. */
+function stackEffect(abc, i) {
+    const info = (0, opcodes_js_1.opInfo)(i.op);
+    if (!info)
+        return { pop: 0, push: 0 };
+    let pop = info.pop;
+    if (info.popArgc) {
+        const argcPos = info.operands.filter((t) => t !== 'branch' && t !== 'switch').indexOf('argc');
+        pop += info.popArgc * (i.args[argcPos] ?? 0);
+    }
+    if (info.popMn) {
+        const mnPos = info.operands.filter((t) => t !== 'branch' && t !== 'switch').indexOf('multiname');
+        pop += multinameRuntimeArity(abc, i.args[mnPos] ?? 0);
+    }
+    return { pop, push: info.push };
+}
+/** Local registers referenced by an instruction. */
+function registersUsed(i) {
+    switch (i.op) {
+        case opcodes_js_1.Op.getlocal0:
+        case opcodes_js_1.Op.setlocal0:
+            return [0];
+        case opcodes_js_1.Op.getlocal1:
+        case opcodes_js_1.Op.setlocal1:
+            return [1];
+        case opcodes_js_1.Op.getlocal2:
+        case opcodes_js_1.Op.setlocal2:
+            return [2];
+        case opcodes_js_1.Op.getlocal3:
+        case opcodes_js_1.Op.setlocal3:
+            return [3];
+        case opcodes_js_1.Op.getlocal:
+        case opcodes_js_1.Op.setlocal:
+        case opcodes_js_1.Op.kill:
+        case opcodes_js_1.Op.inclocal:
+        case opcodes_js_1.Op.declocal:
+        case opcodes_js_1.Op.inclocal_i:
+        case opcodes_js_1.Op.declocal_i:
+            return [i.args[0] ?? 0];
+        case opcodes_js_1.Op.hasnext2:
+            return [i.args[0] ?? 0, i.args[1] ?? 0];
+        case opcodes_js_1.Op.debug:
+            return i.args[0] === 1 ? [i.args[2] ?? 0] : [];
+        default:
+            return [];
+    }
+}
+/**
+ * Computes stack / scope / register requirements by walking all control-flow
+ * paths (including exception handlers).
+ */
+function computeLimits(abc, items, exceptions = []) {
+    const labelIndex = new Map();
+    items.forEach((it, idx) => {
+        if (it.type === 'label')
+            labelIndex.set(it.id, idx);
+    });
+    let maxStack = 0;
+    let maxScope = 0;
+    let registers = 0;
+    for (const it of items)
+        if (it.type === 'op')
+            for (const r of registersUsed(it))
+                registers = Math.max(registers, r + 1);
+    const seenStack = new Int32Array(items.length).fill(-1);
+    const seenScope = new Int32Array(items.length).fill(-1);
+    const work = [[0, 0, 0]];
+    for (const e of exceptions) {
+        const t = labelIndex.get(e.target);
+        if (t !== undefined)
+            work.push([t, 1, 0]);
+    }
+    if (exceptions.length > 0)
+        maxStack = Math.max(maxStack, 1);
+    let budget = items.length * 64 + 1024;
+    while (work.length > 0 && budget-- > 0) {
+        let [idx, stack, scope] = work.pop();
+        while (idx < items.length) {
+            if (stack <= seenStack[idx] && scope <= seenScope[idx])
+                break;
+            seenStack[idx] = Math.max(seenStack[idx], stack);
+            seenScope[idx] = Math.max(seenScope[idx], scope);
+            const it = items[idx];
+            if (it.type === 'label') {
+                idx++;
+                continue;
+            }
+            if (it.type === 'bytes')
+                break;
+            const info = (0, opcodes_js_1.opInfo)(it.op);
+            if (!info)
+                break;
+            const { pop, push } = stackEffect(abc, it);
+            stack = Math.max(0, stack - pop) + push;
+            scope = Math.max(0, scope + info.scope);
+            maxStack = Math.max(maxStack, stack);
+            maxScope = Math.max(maxScope, scope);
+            for (let k = 0; k < it.targets.length; k++) {
+                const t = labelIndex.get(it.targets[k]);
+                if (t !== undefined)
+                    work.push([t, stack, scope]);
+            }
+            if (info.flow === 'jump' || info.flow === 'switch' || info.flow === 'return' || info.flow === 'throw')
+                break;
+            idx++;
+        }
+    }
+    return { maxStack, maxScope, registers };
+}
+/** Minimum local_count required by a method signature (this + params + rest/arguments). */
+function minLocalCount(method) {
+    let n = 1 + method.paramTypes.length;
+    if (method.flags & (constants_js_1.MethodFlags.NEED_REST | constants_js_1.MethodFlags.NEED_ARGUMENTS))
+        n++;
+    return n;
+}
+/**
+ * Structural verification similar to the AVM2 verifier's first pass:
+ * stack underflow, inconsistent stack / scope heights at merge points,
+ * falling off the end of the code and scope underflow.
+ */
+function verifyCode(abc, items, exceptions = []) {
+    const issues = [];
+    const labelIndex = new Map();
+    items.forEach((it, idx) => {
+        if (it.type === 'label')
+            labelIndex.set(it.id, idx);
+    });
+    const stackAt = new Int32Array(items.length + 1).fill(-1);
+    const scopeAt = new Int32Array(items.length + 1).fill(-1);
+    const work = [[0, 0, 0]];
+    for (const e of exceptions) {
+        const t = labelIndex.get(e.target);
+        if (t === undefined)
+            issues.push({ item: -1, message: `Exception target label ${e.target} undefined` });
+        else
+            work.push([t, 1, 0]);
+    }
+    const report = (item, message) => {
+        if (issues.length < 50 && !issues.some((i) => i.item === item && i.message === message))
+            issues.push({ item, message });
+    };
+    while (work.length) {
+        let [idx, stack, scope] = work.pop();
+        while (true) {
+            if (idx >= items.length) {
+                report(idx, 'Control falls off the end of the code');
+                break;
+            }
+            if (stackAt[idx] >= 0) {
+                if (stackAt[idx] !== stack)
+                    report(idx, `Stack height mismatch at merge (${stackAt[idx]} vs ${stack})`);
+                if (scopeAt[idx] !== scope)
+                    report(idx, `Scope height mismatch at merge (${scopeAt[idx]} vs ${scope})`);
+                break;
+            }
+            stackAt[idx] = stack;
+            scopeAt[idx] = scope;
+            const it = items[idx];
+            if (it.type === 'label') {
+                idx++;
+                continue;
+            }
+            if (it.type === 'bytes')
+                break;
+            const info = (0, opcodes_js_1.opInfo)(it.op);
+            if (!info) {
+                report(idx, `Unknown opcode ${it.op}`);
+                break;
+            }
+            const { pop, push } = stackEffect(abc, it);
+            if (pop > stack)
+                report(idx, `Stack underflow in ${info.name} (needs ${pop}, has ${stack})`);
+            stack = Math.max(0, stack - pop) + push;
+            scope += info.scope;
+            if (scope < 0) {
+                report(idx, `Scope underflow in ${info.name}`);
+                scope = 0;
+            }
+            for (const t of it.targets) {
+                const ti = labelIndex.get(t);
+                if (ti === undefined)
+                    report(idx, `Undefined label ${t}`);
+                else
+                    work.push([ti, stack, scope]);
+            }
+            if (info.flow === 'jump' || info.flow === 'switch' || info.flow === 'return' || info.flow === 'throw')
+                break;
+            idx++;
+        }
+    }
+    return issues;
+}

package/dist/cjs/abc/code.d.ts

@@ -0,0 +1,59 @@
+import type { ExceptionInfo } from './abc-file.js';
+export interface Instruction {
+    type: 'op';
+    op: number;
+    /** Non-branch operands in declaration order. */
+    args: number[];
+    /** Label ids of branch targets. lookupswitch: [default, case0, case1, ...]. */
+    targets: number[];
+    /** Byte offset in the original code (-1 for new instructions). */
+    offset: number;
+}
+export interface LabelItem {
+    type: 'label';
+    id: number;
+}
+/** Bytes that are not reachable / not decodable; kept verbatim. */
+export interface BytesItem {
+    type: 'bytes';
+    data: Uint8Array;
+}
+export type CodeItem = Instruction | LabelItem | BytesItem;
+/** Exception table entry with label ids instead of byte offsets. */
+export interface CodeException {
+    from: number;
+    to: number;
+    target: number;
+    excType: number;
+    varName: number;
+}
+export interface DecodedCode {
+    items: CodeItem[];
+    exceptions: CodeException[];
+    /** Next free label id. */
+    nextLabel: number;
+}
+export declare function insn(op: number, args?: number[], targets?: number[]): Instruction;
+export declare class CodeDecodeError extends Error {
+    name: string;
+}
+/**
+ * Decodes method code. Instructions are discovered by following control flow
+ * from the entry point and exception handlers, so junk bytes inserted by
+ * obfuscators are preserved as {@link BytesItem}s instead of breaking decoding.
+ * Falls back to linear decoding when control flow overlaps instructions.
+ *
+ * Throws if the code cannot be represented with labels (e.g. branches
+ * outside the method).
+ */
+export declare function decodeCode(code: Uint8Array, exceptions: readonly ExceptionInfo[]): DecodedCode;
+/** Encoded size of an instruction in bytes. */
+export declare function instructionSize(i: Instruction): number;
+export interface EncodedCode {
+    code: Uint8Array;
+    exceptions: ExceptionInfo[];
+    /** Byte offset of every label id. */
+    labelOffsets: Map<number, number>;
+}
+/** Encodes a label-based instruction list back into bytecode. */
+export declare function encodeCode(items: readonly CodeItem[], exceptions?: readonly CodeException[]): EncodedCode;

package/dist/cjs/abc/code.js

@@ -0,0 +1,387 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeDecodeError = void 0;
+exports.insn = insn;
+exports.decodeCode = decodeCode;
+exports.instructionSize = instructionSize;
+exports.encodeCode = encodeCode;
+/**
+ * AVM2 method body code: decoding to a label-based instruction list and
+ * encoding back to bytes.
+ */
+const reader_js_1 = require("../io/reader.js");
+const writer_js_1 = require("../io/writer.js");
+const opcodes_js_1 = require("./opcodes.js");
+function insn(op, args = [], targets = []) {
+    return { type: 'op', op, args, targets, offset: -1 };
+}
+class CodeDecodeError extends Error {
+    name = "CodeDecodeError";
+}
+exports.CodeDecodeError = CodeDecodeError;
+function readInsn(code, pos) {
+    const info = (0, opcodes_js_1.opInfo)(code[pos]);
+    if (!info)
+        return null;
+    const r = new reader_js_1.ByteReader(code, pos + 1);
+    const args = [];
+    const targets = [];
+    try {
+        for (const t of info.operands) {
+            switch (t) {
+                case 'u8':
+                    args.push(r.u8());
+                    break;
+                case 's8':
+                    args.push(r.s8());
+                    break;
+                case 'short':
+                    args.push(r.encodedU32() | 0);
+                    break;
+                case 'branch': {
+                    const off = r.s24();
+                    targets.push(r.pos + off);
+                    break;
+                }
+                case 'switch': {
+                    targets.push(pos + r.s24());
+                    const count = r.encodedU32();
+                    for (let i = 0; i <= count; i++)
+                        targets.push(pos + r.s24());
+                    break;
+                }
+                default:
+                    args.push(r.encodedU32());
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return { op: info.code, args, targets, length: r.pos - pos };
+}
+function isTerminal(op) {
+    const f = (0, opcodes_js_1.opInfo)(op)?.flow;
+    return f === 'jump' || f === 'switch' || f === 'return' || f === 'throw';
+}
+/**
+ * Decodes method code. Instructions are discovered by following control flow
+ * from the entry point and exception handlers, so junk bytes inserted by
+ * obfuscators are preserved as {@link BytesItem}s instead of breaking decoding.
+ * Falls back to linear decoding when control flow overlaps instructions.
+ *
+ * Throws if the code cannot be represented with labels (e.g. branches
+ * outside the method).
+ */
+function decodeCode(code, exceptions) {
+    try {
+        return decodeWith(code, exceptions, flowDecode(code, exceptions));
+    }
+    catch (e) {
+        if (!(e instanceof CodeDecodeError))
+            throw e;
+        return decodeWith(code, exceptions, linearDecode(code));
+    }
+}
+function flowDecode(code, exceptions) {
+    const len = code.length;
+    const owner = new Int32Array(len).fill(-1); // start offset of the instruction covering each byte
+    const insns = new Map();
+    const work = [0];
+    for (const e of exceptions)
+        work.push(e.target);
+    while (work.length > 0) {
+        let pos = work.pop();
+        while (pos >= 0 && pos < len) {
+            if (insns.has(pos))
+                break;
+            if (owner[pos] !== -1)
+                throw new CodeDecodeError(`Overlapping instruction at ${pos}`);
+            const ins = readInsn(code, pos);
+            // Unknown opcode, or a branch leaving the method: keep as raw bytes.
+            if (!ins || ins.targets.some((t) => t < 0 || t > len))
+                break;
+            for (let i = 0; i < ins.length; i++) {
+                if (owner[pos + i] !== -1)
+                    throw new CodeDecodeError(`Overlapping instruction at ${pos + i}`);
+                owner[pos + i] = pos;
+            }
+            insns.set(pos, ins);
+            for (const t of ins.targets)
+                work.push(t);
+            if (isTerminal(ins.op))
+                break;
+            pos += ins.length;
+        }
+    }
+    decodeGaps(code, insns);
+    return insns;
+}
+/**
+ * Unreachable regions (dead code emitted by compilers, or obfuscator junk)
+ * are decoded linearly when they decode cleanly into whole instructions whose
+ * branch targets are valid; otherwise they stay raw bytes.
+ */
+function decodeGaps(code, insns) {
+    const len = code.length;
+    const sorted = [...insns.keys()].sort((a, b) => a - b);
+    const gaps = [];
+    let pos = 0;
+    for (const s of sorted) {
+        if (s > pos)
+            gaps.push({ start: pos, end: s });
+        pos = Math.max(pos, s + insns.get(s).length);
+    }
+    if (pos < len)
+        gaps.push({ start: pos, end: len });
+    const candidates = [];
+    for (const g of gaps) {
+        const found = new Map();
+        let p = g.start;
+        let ok = true;
+        while (p < g.end) {
+            const ins = readInsn(code, p);
+            if (!ins || p + ins.length > g.end || ins.targets.some((t) => t < 0 || t > len)) {
+                ok = false;
+                break;
+            }
+            found.set(p, ins);
+            p += ins.length;
+        }
+        if (ok && found.size > 0)
+            candidates.push(found);
+    }
+    // Accept gap decodings whose targets all land on instruction boundaries.
+    let changed = true;
+    let accepted = candidates;
+    while (changed) {
+        changed = false;
+        const starts = new Set(insns.keys());
+        for (const c of accepted)
+            for (const k of c.keys())
+                starts.add(k);
+        starts.add(len);
+        const next = accepted.filter((c) => {
+            for (const ins of c.values())
+                for (const t of ins.targets)
+                    if (!starts.has(t))
+                        return false;
+            return true;
+        });
+        if (next.length !== accepted.length) {
+            accepted = next;
+            changed = true;
+        }
+    }
+    for (const c of accepted)
+        for (const [k, v] of c)
+            insns.set(k, v);
+}
+function linearDecode(code) {
+    const insns = new Map();
+    let pos = 0;
+    while (pos < code.length) {
+        const ins = readInsn(code, pos);
+        if (!ins) {
+            pos++;
+            continue;
+        }
+        insns.set(pos, ins);
+        pos += ins.length;
+    }
+    return insns;
+}
+function decodeWith(code, exceptions, insns) {
+    const len = code.length;
+    const starts = new Uint8Array(len + 1); // 1 = instruction start, 2 = inside instruction
+    for (const [pos, ins] of insns) {
+        starts[pos] = 1;
+        for (let i = 1; i < ins.length; i++)
+            starts[pos + i] = 2;
+    }
+    const labelAt = new Map();
+    let nextLabel = 0;
+    const label = (offset) => {
+        if (offset < 0 || offset > len)
+            throw new CodeDecodeError(`Branch/exception offset ${offset} outside code (0..${len})`);
+        if (starts[offset] === 2)
+            throw new CodeDecodeError(`Offset ${offset} points inside an instruction`);
+        let id = labelAt.get(offset);
+        if (id === undefined) {
+            id = nextLabel++;
+            labelAt.set(offset, id);
+        }
+        return id;
+    };
+    // Allocate labels in offset order for readable output.
+    const wanted = new Set();
+    for (const ins of insns.values())
+        for (const t of ins.targets)
+            wanted.add(t);
+    for (const e of exceptions) {
+        wanted.add(e.from);
+        wanted.add(e.to);
+        wanted.add(e.target);
+    }
+    for (const off of [...wanted].sort((a, b) => a - b))
+        label(off);
+    const items = [];
+    let rawStart = -1;
+    const flushRaw = (end) => {
+        if (rawStart >= 0) {
+            items.push({ type: 'bytes', data: code.slice(rawStart, end) });
+            rawStart = -1;
+        }
+    };
+    let pos = 0;
+    while (pos <= len) {
+        const l = labelAt.get(pos);
+        if (l !== undefined) {
+            flushRaw(pos);
+            items.push({ type: 'label', id: l });
+        }
+        if (pos === len)
+            break;
+        const ins = insns.get(pos);
+        if (ins) {
+            flushRaw(pos);
+            items.push({
+                type: 'op',
+                op: ins.op,
+                args: ins.args,
+                targets: ins.targets.map((t) => labelAt.get(t)),
+                offset: pos,
+            });
+            pos += ins.length;
+        }
+        else {
+            if (rawStart < 0)
+                rawStart = pos;
+            pos++;
+        }
+    }
+    flushRaw(len);
+    return {
+        items,
+        exceptions: exceptions.map((e) => ({
+            from: labelAt.get(e.from),
+            to: labelAt.get(e.to),
+            target: labelAt.get(e.target),
+            excType: e.excType,
+            varName: e.varName,
+        })),
+        nextLabel,
+    };
+}
+function u30Size(v) {
+    v >>>= 0;
+    let n = 1;
+    while (v >= 0x80) {
+        v >>>= 7;
+        n++;
+    }
+    return n;
+}
+function operandSize(t, value) {
+    switch (t) {
+        case 'u8':
+        case 's8':
+            return 1;
+        case 'branch':
+            return 3;
+        default:
+            return u30Size(value);
+    }
+}
+/** Encoded size of an instruction in bytes. */
+function instructionSize(i) {
+    const info = (0, opcodes_js_1.opInfo)(i.op);
+    if (!info)
+        throw new Error(`Unknown opcode 0x${i.op.toString(16)}`);
+    let size = 1;
+    let argIndex = 0;
+    for (const t of info.operands) {
+        if (t === 'switch') {
+            if (i.targets.length < 2)
+                throw new Error('lookupswitch needs a default target and at least one case');
+            size += 3 + u30Size(i.targets.length - 2) + 3 * (i.targets.length - 1);
+        }
+        else if (t === 'branch') {
+            size += 3;
+        }
+        else {
+            size += operandSize(t, i.args[argIndex++] ?? 0);
+        }
+    }
+    return size;
+}
+/** Encodes a label-based instruction list back into bytecode. */
+function encodeCode(items, exceptions = []) {
+    const labelOffsets = new Map();
+    let offset = 0;
+    for (const item of items) {
+        if (item.type === 'label') {
+            if (labelOffsets.has(item.id))
+                throw new Error(`Label ${item.id} defined twice`);
+            labelOffsets.set(item.id, offset);
+        }
+        else if (item.type === 'bytes')
+            offset += item.data.length;
+        else
+            offset += instructionSize(item);
+    }
+    const target = (id) => {
+        const o = labelOffsets.get(id);
+        if (o === undefined)
+            throw new Error(`Undefined label ${id}`);
+        return o;
+    };
+    const w = new writer_js_1.ByteWriter(offset + 16);
+    for (const item of items) {
+        if (item.type === 'label')
+            continue;
+        if (item.type === 'bytes') {
+            w.bytes(item.data);
+            continue;
+        }
+        const start = w.length;
+        const info = (0, opcodes_js_1.opInfo)(item.op);
+        w.u8(item.op);
+        let argIndex = 0;
+        for (const t of info.operands) {
+            switch (t) {
+                case 'u8':
+                    w.u8(item.args[argIndex++] ?? 0);
+                    break;
+                case 's8':
+                    w.s8(item.args[argIndex++] ?? 0);
+                    break;
+                case 'branch': {
+                    const end = w.length + 3;
+                    w.s24(target(item.targets[0]) - end);
+                    break;
+                }
+                case 'switch': {
+                    w.s24(target(item.targets[0]) - start);
+                    w.encodedU32(item.targets.length - 2);
+                    for (let k = 1; k < item.targets.length; k++)
+                        w.s24(target(item.targets[k]) - start);
+                    break;
+                }
+                default:
+                    w.encodedU32((item.args[argIndex++] ?? 0) >>> 0);
+            }
+        }
+    }
+    return {
+        code: w.toBytes(),
+        exceptions: exceptions.map((e) => ({
+            from: target(e.from),
+            to: target(e.to),
+            target: target(e.target),
+            excType: e.excType,
+            varName: e.varName,
+        })),
+        labelOffsets,
+    };
+}