luau-obfuscator 1.0.0

package/scripts/test.js

@@ -0,0 +1,8 @@
+import fs from 'fs'
+import { obfuscate } from '../dist/index.js'
+
+const exampleScript = fs.readFileSync('./scripts/example.luau', 'utf-8')
+const obfuscated = obfuscate(exampleScript, {
+    Minify: {active: false}
+})
+fs.writeFileSync('./generated/final.luau', obfuscated)

package/src/config.ts

@@ -0,0 +1,80 @@
+import type { StringsToExpressionsOptions } from "./passes/StringsToExpressions"
+import type { NumbersToExpressionsOptions } from "./passes/NumbersToExpressions"
+import type { RenameVariablesOptions } from "./passes/RenameVariables"
+import type { GlobalMappingOptions } from "./passes/GlobalMapping"
+import type { EncryptStringsOptions } from "./passes/EncryptStrings"
+import type { EncryptNumbersOptions } from "./passes/EncryptNumbers"
+
+export type ObfuscateConfigEach<C> = ({
+    active: true
+} & C) | {
+    active: false
+}
+
+// 각 feature의 옵션 타입은 여기서 새로 선언하지 않고 해당 패스 파일에서 export한
+// *Options 타입을 그대로 참조한다. 옵션 모양이 바뀌면 패스 파일 하나만 고치면 됨.
+export type ObfuscateConfig = {
+    Vmify: ObfuscateConfigEach<{}>
+    Minify: ObfuscateConfigEach<{}>
+    StringsToExpressions: ObfuscateConfigEach<StringsToExpressionsOptions>
+    NumbersToExpressions: ObfuscateConfigEach<NumbersToExpressionsOptions>
+    EncryptStrings: ObfuscateConfigEach<EncryptStringsOptions>
+    EncryptNumbers: ObfuscateConfigEach<EncryptNumbersOptions>
+    RenameVariables: ObfuscateConfigEach<RenameVariablesOptions>
+    GlobalMapping: ObfuscateConfigEach<GlobalMappingOptions>
+    ConstantArray: ObfuscateConfigEach<{}>
+    InsertJunk: ObfuscateConfigEach<{ probability: number, maxPerBlock: number }>
+    WrapInFunction: ObfuscateConfigEach<{}>
+}
+
+// active:true 분기의 옵션 타입만 추출 (naked type param에 대한 distributive conditional type)
+type ExtractOptions<T> = T extends { active: true } ? Omit<T, "active"> : never
+
+/**
+ * 사용자가 넘기는 partial config.
+ * 각 feature는 `{active:false}`를 통째로 넘기거나,
+ * `{active:true}` + 옵션 일부만 override 하는 형태만 허용.
+ * (재귀적 DeepMerge는 이 판별 유니온 구조를 깨서 쓰지 않음)
+ */
+export type ObfuscatePartialConfig = {
+    [K in keyof ObfuscateConfig]?:
+        | { active: false }
+        | ({ active: true } & Partial<ExtractOptions<ObfuscateConfig[K]>>)
+}
+
+export const ObfuscateDefault: ObfuscateConfig = {
+    Vmify: { active: true },
+    Minify: { active: true },
+    StringsToExpressions: { active: true, min: 5, max: 10 },
+    NumbersToExpressions: { active: true, min: 5, max: 10 },
+    EncryptStrings: { active: true },
+    EncryptNumbers: { active: true },
+    RenameVariables: { active: true, random: () => "_" + globalThis.crypto.randomUUID().replace(/-/g, "") },
+    GlobalMapping: { active: true, tableName: "GLOBAL" },
+    ConstantArray: { active: true },
+    InsertJunk: { active: true, probability: 0.7, maxPerBlock: 5 },
+    WrapInFunction: { active: true },
+}
+
+export function mergeConfig(
+    defaults: ObfuscateConfig,
+    partial: ObfuscatePartialConfig,
+): ObfuscateConfig {
+    const result = {} as ObfuscateConfig
+
+    for (const key of Object.keys(defaults) as (keyof ObfuscateConfig)[]) {
+        const def = defaults[key]
+        const part = partial[key]
+
+        if (!part) {
+            (result as any)[key] = def
+        } else if (part.active === false) {
+            (result as any)[key] = { active: false }
+        } else {
+            // active:true -> 기본값 위에 override만 얕게 덮어씀 (재귀 병합 없음)
+            (result as any)[key] = { ...(def as object), ...(part as object), active: true }
+        }
+    }
+
+    return result
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import type { Program } from "luau-parser"
+import { luauparser } from "luau-parser"
+import type { ObfuscateConfig, ObfuscateConfigEach, ObfuscatePartialConfig } from "./config"
+import { ObfuscateDefault, mergeConfig } from "./config"
+import { runPipeline } from "./pipeline"
+import { minifyPrinted } from "./passes/Minify"
+
+export type { ObfuscateConfig, ObfuscateConfigEach, ObfuscatePartialConfig } from "./config"
+export { ObfuscateDefault } from "./config"
+export { PASS_ORDER, PASS_MAP } from "./pipeline"
+
+export function obfuscateByAst(program: Program, PConfig?: ObfuscatePartialConfig): string {
+    const config = mergeConfig(ObfuscateDefault, PConfig ?? {})
+    runPipeline(program, config)
+    const printed = luauparser.print(program)
+    return config.Minify.active ? minifyPrinted(printed) : printed
+}
+
+export function obfuscate(source: string, PConfig?: ObfuscatePartialConfig): string {
+    const program = luauparser.parse(source)
+    return obfuscateByAst(program, PConfig)
+}

package/src/passes/ConstantArray.ts

@@ -0,0 +1,90 @@
+import type { Program, TableField } from "luau-parser"
+import { transformExpressions } from "./walk"
+import {
+    stringLiteral, numberLiteral, index as indexExpr, identifier, table, localStatement,
+} from "./nodeFactory"
+
+export interface ConstantArrayOptions {
+    /** 상수 배열을 담을 local 변수 이름. 생략하면 랜덤 생성됨
+     *  (어차피 RenameVariables가 이후에 한 번 더 이름을 바꿔줌). */
+    arrayName?: string
+}
+
+type Entry = { kind: "string"; value: string } | { kind: "number"; value: number }
+type ConstKey = string
+
+function keyOf(kind: Entry["kind"], value: string | number): ConstKey {
+    return kind === "string" ? `s:${value}` : `n:${value}`
+}
+
+function shuffleIndices(length: number): number[] {
+    const order = Array.from({ length }, (_, i) => i)
+    for (let i = order.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1))
+        ;[order[i], order[j]] = [order[j], order[i]]
+    }
+    return order
+}
+
+function defaultArrayName(): string {
+    return "_CA" + Math.random().toString(36).slice(2, 8)
+}
+
+export function runConstantArray(program: Program, options: ConstantArrayOptions): void {
+    const order: Entry[] = []
+    const seen = new Set<ConstKey>()
+
+    transformExpressions(program, (expr) => {
+        if (expr.type === "StringLiteral") {
+            const k = keyOf("string", expr.value)
+            if (!seen.has(k)) {
+                seen.add(k)
+                order.push({ kind: "string", value: expr.value })
+            }
+        } else if (expr.type === "NumberLiteral") {
+            const k = keyOf("number", expr.value)
+            if (!seen.has(k)) {
+                seen.add(k)
+                order.push({ kind: "number", value: expr.value })
+            }
+        }
+        return undefined
+    })
+
+    if (order.length === 0) return
+
+    // 2) 배열 안에서 실제로 놓일 위치를 등장 순서와 다르게 섞음.
+    //    shuffledOrder[슬롯] = order 배열에서의 원래 인덱스
+    const shuffledOrder = shuffleIndices(order.length)
+    const indexOf = new Map<ConstKey, number>() // 상수 키 -> 1-based 배열 인덱스
+    shuffledOrder.forEach((originalIndex, slot) => {
+        const entry = order[originalIndex]
+        indexOf.set(keyOf(entry.kind, entry.value), slot + 1)
+    })
+
+    const arrayName = options.arrayName ?? defaultArrayName()
+
+    // 3) 기존 트리를 돌면서 리터럴을 ARR[idx] 접근으로 치환.
+    //    배열 선언문은 아직 트리에 넣지 않은 상태에서 해야 함 — 넣고 나서 돌리면
+    //    배열 자신의 값들까지 자기 자신을 가리키게 치환돼서 깨짐.
+    transformExpressions(program, (expr) => {
+        if (expr.type === "StringLiteral") {
+            const idx = indexOf.get(keyOf("string", expr.value))!
+            return indexExpr(identifier(arrayName), numberLiteral(idx))
+        }
+        if (expr.type === "NumberLiteral") {
+            const idx = indexOf.get(keyOf("number", expr.value))!
+            return indexExpr(identifier(arrayName), numberLiteral(idx))
+        }
+        return undefined
+    })
+
+    // 4) 치환이 끝난 뒤에야 배열 선언문을 맨 위에 삽입.
+    const fields: TableField[] = shuffledOrder.map((originalIndex) => {
+        const entry = order[originalIndex]
+        const value = entry.kind === "string" ? stringLiteral(entry.value) : numberLiteral(entry.value)
+        return { type: "TableFieldPositional", value }
+    })
+
+    program.body.statements.unshift(localStatement(arrayName, table(fields)))
+}

package/src/passes/EncryptNumbers.ts

@@ -0,0 +1,66 @@
+import type { Program, Expression } from "luau-parser"
+import { transformExpressions } from "./walk"
+import {
+    identifier, numberLiteral, call, member,
+    localFunctionStatement, functionParam, functionBody, block, returnStatement,
+} from "./nodeFactory"
+
+export interface EncryptNumbersOptions {}
+
+// bit32.bxor는 32비트 부호 없는 정수만 다룸. 실수/음수/범위 밖 값은 그대로 둔다
+// (그런 값은 NumbersToExpressions 쪽 산술식 위장으로 커버).
+const UINT32_MAX = 0xFFFFFFFF
+
+function randomInt(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min
+}
+
+function randomName(): string {
+    return "_" + globalThis.crypto.randomUUID().replace(/-/g, "")
+}
+
+function isEncryptable(value: number): boolean {
+    return Number.isInteger(value) && value >= 0 && value <= UINT32_MAX
+}
+
+/** JS의 ^ 연산자는 32비트 부호 있는 정수로 계산하므로 >>> 0으로 다시
+ *  부호 없는 32비트 표현으로 맞춰줌 — bit32.bxor와 동일한 비트 결과가 나옴. */
+function xor32(a: number, b: number): number {
+    return (a ^ b) >>> 0
+}
+
+/**
+ * local function <name>(n, key)
+ *     return bit32.bxor(n, key)
+ * end
+ */
+function buildDecoderStatement(name: string) {
+    const nParam = randomName()
+    const keyParam = randomName()
+
+    const body = block([
+        returnStatement([call(member(identifier("bit32"), "bxor"), [identifier(nParam), identifier(keyParam)])]),
+    ])
+
+    return localFunctionStatement(name, functionBody([functionParam(nParam), functionParam(keyParam)], body))
+}
+
+export function runEncryptNumbers(program: Program, _options: EncryptNumbersOptions): void {
+    const decoderName = randomName()
+    let used = false
+
+    transformExpressions(program, (expr: Expression) => {
+        if (expr.type !== "NumberLiteral") return
+        if (!isEncryptable(expr.value)) return
+
+        used = true
+        const key = randomInt(1, 0xFFFFFF)
+        const encoded = xor32(expr.value, key)
+
+        return call(identifier(decoderName), [numberLiteral(encoded), numberLiteral(key)])
+    })
+
+    if (!used) return
+
+    program.body.statements.unshift(buildDecoderStatement(decoderName))
+}

package/src/passes/EncryptStrings.ts

@@ -0,0 +1,83 @@
+import type { Program, Expression } from "luau-parser"
+import { transformExpressions } from "./walk"
+import {
+    identifier, numberLiteral, call, member, index, table, positionalField,
+    localFunctionStatement, functionParam, functionBody, block, localStatement,
+    assignmentStatement, numericForStatement, returnStatement, unary,
+} from "./nodeFactory"
+
+export interface EncryptStringsOptions {}
+
+function randomInt(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min
+}
+
+function randomName(): string {
+    return "_" + globalThis.crypto.randomUUID().replace(/-/g, "")
+}
+
+/** Luau 소스는 UTF-8 바이트 스트림이므로 charCodeAt이 아니라 실제 UTF-8 바이트로 변환. */
+function toUtf8Bytes(value: string): number[] {
+    return Array.from(new TextEncoder().encode(value))
+}
+
+/**
+ * 런타임 디코더를 조립:
+ *   local function <name>(data, key)
+ *       local out = {}
+ *       for i = 1, #data do
+ *           out[i] = string.char(bit32.bxor(data[i], key))
+ *       end
+ *       return table.concat(out)
+ *   end
+ */
+function buildDecoderStatement(name: string) {
+    const dataParam = randomName()
+    const keyParam = randomName()
+    const outVar = randomName()
+    const iVar = randomName()
+
+    const body = block([
+        localStatement(outVar, table([])),
+        numericForStatement(
+            iVar,
+            numberLiteral(1),
+            unary("#", identifier(dataParam)),
+            block([
+                assignmentStatement(
+                    [index(identifier(outVar), identifier(iVar))],
+                    [call(member(identifier("string"), "char"), [
+                        call(member(identifier("bit32"), "bxor"), [
+                            index(identifier(dataParam), identifier(iVar)),
+                            identifier(keyParam),
+                        ]),
+                    ])],
+                ),
+            ]),
+        ),
+        returnStatement([call(member(identifier("table"), "concat"), [identifier(outVar)])]),
+    ])
+
+    return localFunctionStatement(name, functionBody([functionParam(dataParam), functionParam(keyParam)], body))
+}
+
+export function runEncryptStrings(program: Program, _options: EncryptStringsOptions): void {
+    const decoderName = randomName()
+    let used = false
+
+    transformExpressions(program, (expr: Expression) => {
+        if (expr.type !== "StringLiteral") return
+        if (expr.value.length === 0) return
+
+        used = true
+        const key = randomInt(1, 255)
+        const bytes = toUtf8Bytes(expr.value).map((b) => b ^ key)
+        const dataTable = table(bytes.map((b) => positionalField(numberLiteral(b))))
+
+        return call(identifier(decoderName), [dataTable, numberLiteral(key)])
+    })
+
+    if (!used) return
+
+    program.body.statements.unshift(buildDecoderStatement(decoderName))
+}

package/src/passes/GlobalMapping.ts

@@ -0,0 +1,194 @@
+import type {
+    Program, Block, Statement, Expression, Identifier, ScopeAnalysis,
+} from "luau-parser"
+import { analyzeScopes, isGlobal, getBinding } from "luau-parser"
+import {
+    identifier, numberLiteral, stringLiteral, index as indexExpr,
+    table, computedField, localStatement,
+} from "./nodeFactory"
+
+export interface GlobalMappingOptions {
+    /** 전역들을 담아둘 최상단 local 테이블 변수 이름. RenameVariables가 이후에
+     *  다시 실행되면 이 이름도 다른 이름으로 한 번 더 바뀜. */
+    tableName: string
+}
+
+type Key = number | string
+
+function randomInt(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min
+}
+
+function randomKey(): Key {
+    // 숫자 키/문자열 키를 섞어서 접근 패턴을 예측하기 어렵게 함
+    if (Math.random() < 0.5) return randomInt(1, 50)
+    const chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    const len = randomInt(2, 4)
+    let s = ""
+    for (let i = 0; i < len; i++) s += chars[randomInt(0, chars.length - 1)]
+    return s
+}
+
+function randomPath(): Key[] {
+    const depth = randomInt(2, 4)
+    const path: Key[] = []
+    for (let i = 0; i < depth; i++) path.push(randomKey())
+    return path
+}
+
+type TreeLeaf = { leaf: string }
+type TreeNode = Map<Key, TreeNode | TreeLeaf>
+
+function isLeaf(v: TreeNode | TreeLeaf): v is TreeLeaf {
+    return !(v instanceof Map)
+}
+
+/** path를 따라 내려가며 중간 노드를 만들고 마지막 키에 리프를 심음.
+ *  경로 충돌(이미 다른 값이 있음)이 나면 false를 반환 — 호출 쪽에서 다른 경로로 재시도. */
+function insertPath(root: TreeNode, path: Key[], globalName: string): boolean {
+    let node = root
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i]
+        let next = node.get(key)
+        if (next === undefined) {
+            next = new Map()
+            node.set(key, next)
+        } else if (isLeaf(next)) {
+            return false
+        }
+        node = next as TreeNode
+    }
+    const lastKey = path[path.length - 1]
+    if (node.has(lastKey)) return false
+    node.set(lastKey, { leaf: globalName })
+    return true
+}
+
+function assignPaths(globalNames: string[]): { root: TreeNode; paths: Map<string, Key[]> } {
+    const root: TreeNode = new Map()
+    const paths = new Map<string, Key[]>()
+
+    for (const name of globalNames) {
+        let path: Key[] = []
+        let attempts = 0
+        let ok = false
+        while (!ok && attempts < 200) {
+            path = randomPath()
+            ok = insertPath(root, path, name)
+            attempts++
+        }
+        paths.set(name, path)
+    }
+
+    return { root, paths }
+}
+
+function keyExpression(key: Key): Expression {
+    return typeof key === "number" ? numberLiteral(key) : stringLiteral(key)
+}
+
+function buildTreeTableExpr(node: TreeNode): Expression {
+    const fields = [...node.entries()].map(([key, value]) =>
+        computedField(
+            keyExpression(key),
+            isLeaf(value) ? identifier(value.leaf) : buildTreeTableExpr(value),
+        ),
+    )
+    return table(fields)
+}
+
+function buildIndexChain(tableName: string, path: Key[]): Expression {
+    let expr: Expression = identifier(tableName)
+    for (const key of path) {
+        expr = indexExpr(expr, keyExpression(key))
+    }
+    return expr
+}
+
+/** node(원래 Identifier)를 같은 객체 참조를 유지한 채로 IndexExpression으로
+ *  제자리 변형함 — 이 객체를 들고 있는 부모 필드(BinaryExpression.left 등)는
+ *  어디 있는지 몰라도 되고, 그냥 이 객체가 바뀌면 자동으로 반영됨. */
+function morphIntoIndexChain(node: Identifier, tableName: string, path: Key[]): void {
+    const built = buildIndexChain(tableName, path) as unknown as Record<string, unknown>
+    const target = node as unknown as Record<string, unknown>
+    for (const k of Object.keys(target)) delete target[k]
+    Object.assign(target, built)
+}
+
+/**
+ * `function Foo() end` / `function T.m() end` 형태의 target.base는 리터럴
+ * 이름만 허용되는 문법 자리라 인덱스 체인으로 바꿀 수 없음. 이런 자리에 쓰인
+ * 전역 이름은 매핑 대상에서 제외한다.
+ * (statement 트리를 따라 내려가며 찾음 — 익명함수 표현식 내부에 중첩된
+ * 전역 함수 선언 같은 극단적 케이스는 대상에서 빠질 수 있음)
+ */
+function collectUnsafeFunctionDeclGlobals(program: Program, analysis: ScopeAnalysis): Set<string> {
+    const unsafe = new Set<string>()
+
+    function visitBlock(block: Block): void {
+        for (const stmt of block.statements) visitStatement(stmt)
+    }
+
+    function visitStatement(stmt: Statement): void {
+        switch (stmt.type) {
+            case "FunctionDeclarationStatement": {
+                const binding = getBinding(analysis, stmt.target.base)
+                if (binding && isGlobal(binding)) unsafe.add(binding.name)
+                visitBlock(stmt.func.body)
+                return
+            }
+            case "LocalFunctionStatement":
+                visitBlock(stmt.func.body)
+                return
+            case "DoStatement":
+                visitBlock(stmt.body)
+                return
+            case "WhileStatement":
+                visitBlock(stmt.body)
+                return
+            case "RepeatStatement":
+                visitBlock(stmt.body)
+                return
+            case "IfStatement":
+                for (const clause of stmt.clauses) visitBlock(clause.body)
+                if (stmt.alternate) visitBlock(stmt.alternate)
+                return
+            case "NumericForStatement":
+                visitBlock(stmt.body)
+                return
+            case "GenericForStatement":
+                visitBlock(stmt.body)
+                return
+            default:
+                return
+        }
+    }
+
+    visitBlock(program.body)
+    return unsafe
+}
+
+export function runGlobalMapping(program: Program, options: GlobalMappingOptions): void {
+    const analysis = analyzeScopes(program)
+    const unsafe = collectUnsafeFunctionDeclGlobals(program, analysis)
+
+    const globalBindings = [...analysis.bindings.values()].filter(
+        (b) => isGlobal(b) && b.references.length > 0 && !unsafe.has(b.name),
+    )
+    if (globalBindings.length === 0) return
+
+    const { root, paths } = assignPaths(globalBindings.map((b) => b.name))
+
+    for (const binding of globalBindings) {
+        const path = paths.get(binding.name)!
+        // declarationNode(대입으로 정의된 경우)는 이미 references에 포함된
+        // 같은 객체라 references만 돌면 전부 커버됨
+        for (const ref of binding.references) {
+            morphIntoIndexChain(ref, options.tableName, path)
+        }
+    }
+
+    program.body.statements.unshift(
+        localStatement(options.tableName, buildTreeTableExpr(root)),
+    )
+}