ghard13

ghard13 architecture documentation

comprehensive architecture overview and design decisions

system overview

ghard13 implements a dual-layer hardening approach:

  1. content obfuscation: remaps html/css/js selectors to hex values
  2. behavioral puzzles: prevents automated access via human verification

core philosophy

architectural components

component hierarchy

ghard13 (main library)
├── core/
│   ├── obfuscator          # hex value generation and mapping
│   ├── selector_oracle     # selector extraction and tracking
│   └── remapper           # html/css/js content transformation
├── puzzle/
│   ├── puzzle_engine      # puzzle generation and validation
│   ├── puzzle_generator   # behavioral puzzle creation
│   ├── puzzle_ui          # ui component generation
│   └── puzzle_validator   # solution validation logic
└── session/
    ├── session_manager    # session lifecycle management
    ├── session_store      # session persistence
    ├── session_validator  # session validation logic
    ├── session_factory    # session creation
    └── fallback_handler   # puzzle failure management

core components

obfuscator

purpose: generates deterministic hex mappings for selectors

key features:

algorithm:

// deterministic hex generation
function generate_hex(selector, site_salt, length) {
  const seed = hash(selector + site_salt);
  return generate_from_seed(seed, length);
}

design decisions:

selector_oracle

purpose: extracts and tracks selectors across html/css/js files

extraction patterns:

cross-reference tracking:

// tracks selector usage across file types
{
  'main': {
    html: ['id="main"'],
    css: ['#main'],
    js: ['getElementById("main")']
  }
}

design decisions:

remapper

purpose: transforms content using obfuscated mappings

transformation process:

  1. receive original content + mappings
  2. apply regex-based replacements
  3. preserve functionality and structure
  4. return transformed content

replacement strategies:

design decisions:

puzzle system

puzzle_engine

purpose: coordinates puzzle generation and validation

puzzle types:

validation criteria:

puzzle_generator

purpose: creates randomized behavioral puzzles

generation algorithm:

function generate_puzzle() {
  return {
    wait_time: random(2000, 5000),      // 2-5 seconds
    slider_target: random(11, 87),      // 11-87%
    input_word: random_word_from_set(), // DONE, READY, HARD, OK13
    timeout: 60000                      // 60 seconds
  };
}

randomization factors:

puzzle_validator

purpose: validates puzzle solutions with behavioral analysis

validation layers:

  1. solution correctness: values within acceptable ranges
  2. timing analysis: human-like completion times
  3. behavioral patterns: mouse/keyboard behavior analysis
  4. sequence validation: correct action order

behavioral thresholds:

session management

session_manager

purpose: manages session lifecycle and validation

session states:

state transitions:

new → puzzle_pending → puzzle_solved → expired
  ↓         ↓              ↓
fallback ← fallback ← fallback

fallback_handler

purpose: manages puzzle failure scenarios

fallback triggers:

fallback strategy:

  1. serve obfuscated content (still provides protection)
  2. log failure for analysis
  3. apply progressive restrictions
  4. eventual session termination

data flow

buildtime processing

source files → selector_oracle → obfuscator → remapper → hardened files
     ↓              ↓              ↓           ↓
   html/css/js → selectors → mappings → transformations → output

runtime processing

request → session_check → puzzle_required? → puzzle_generation → validation
    ↓          ↓               ↓                   ↓              ↓
response ← content ← fallback_content ← puzzle_ui ← behavioral_analysis

performance considerations

optimization strategies

buildtime vs runtime:

hex pool management:

memory usage:

scalability factors

concurrent sessions:

content size:

security model

threat model

targeted threats:

protection mechanisms:

security assumptions

trusted environment:

limitations:

extensibility

plugin architecture

future extensions:

configuration flexibility

runtime configuration:

design decisions rationale

deterministic obfuscation

decision: use deterministic hex generation vs random rationale: ensures consistent mappings across builds, enables caching

regex-based transformation

decision: regex replacement vs ast parsing rationale: balance between accuracy and performance for most use cases

behavioral puzzle design

decision: multi-factor behavioral validation vs simple captcha rationale: more effective against sophisticated automation

buildtime processing preference

decision: recommend buildtime vs runtime processing rationale: better performance, reduced server load, consistent output

testing strategy

unit testing

component isolation: each module tested independently mock dependencies: external dependencies mocked for reliability edge case coverage: boundary conditions and error scenarios

integration testing

end-to-end workflows: complete hardening and puzzle workflows cross-component interaction: selector extraction → obfuscation → remapping configuration validation: various configuration combinations

performance testing

benchmark scenarios: content size and complexity variations memory profiling: memory usage under different loads scalability testing: concurrent session handling

deployment considerations

production deployment

build integration: integrate with existing build pipelines environment configuration: separate config for dev/staging/prod monitoring: log puzzle success rates and performance metrics

maintenance workflow

content updates: re-run hardening after source changes configuration tuning: adjust based on legitimate user feedback security updates: regular review of obfuscation effectiveness

future roadmap

planned enhancements

potential improvements

advanced obfuscation: css class name mangling, js variable renaming performance optimization: streaming processing, worker threads analytics dashboard: puzzle success rate monitoring

This site is open source. Improve this page.