whitemagic/openspec/changes/whitemagic-foundation/specs/dll-injection/spec.md

ADDED Requirements

Requirement: DLL injection via remote thread

WhiteMagic SHALL inject a DLL into an open target process by creating a remote thread on LoadLibrary, returning the base address of the injected module on success and reporting failure without throwing for expected failure conditions.

Scenario: successful injection

• WHEN a valid DLL path is injected into an open process of matching bitness
• THEN the returned base address MUST be non-zero and the module MUST be loaded in the target

Scenario: bitness mismatch rejected

• WHEN the target process bitness differs from the caller
• THEN injection MUST fail with a clear error rather than corrupt the target

Scenario: missing file

• WHEN the DLL path does not exist
• THEN injection MUST report an argument error

Requirement: DLL injection via thread hijack

WhiteMagic SHALL inject a DLL by hijacking an existing thread — saving its context, redirecting execution through a LoadLibrary stub, and restoring the original context — returning the injected module base address.

Scenario: hijack loads the module

• WHEN a valid DLL is injected by hijacking a running thread
• THEN the module MUST be loaded and the hijacked thread's original context MUST be restored

Scenario: exit code reports load result

• WHEN the redirect stub completes
• THEN the stub MUST record LoadLibrary's result so the caller can detect load success or failure

Requirement: x86 and x64 stubs

Injection stubs SHALL be emitted correctly for both x86 and x64 targets, including proper x64 addressing.

Scenario: x86 stub

• WHEN injecting into a 32-bit target
• THEN a 32-bit redirect stub MUST be emitted

Scenario: x64 stub

• WHEN injecting into a 64-bit target
• THEN a 64-bit redirect stub with correct absolute/RIP-relative addressing MUST be emitted

Requirement: Raw code injection

WhiteMagic SHALL inject raw machine-code bytes into an open process, either at a caller-supplied address or into freshly allocated remote memory whose address is returned.

Scenario: inject at address

• WHEN raw bytes are injected at a given address
• THEN memory at that address MUST equal the injected bytes

Scenario: inject into fresh allocation

• WHEN raw bytes are injected without an address
• THEN remote memory MUST be allocated, the bytes written, and the allocation address returned