+
+
+
+
+
+
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/internal/puzzle_ui/injectBundleJSToIndexHTML.js b/internal/puzzle_ui/injectBundleJSToIndexHTML.js
new file mode 100644
index 0000000..31748a9
--- /dev/null
+++ b/internal/puzzle_ui/injectBundleJSToIndexHTML.js
@@ -0,0 +1,37 @@
+import path from "path"
+import fs from "fs"
+
+
+export default function injectBundleJSToIndexHTML(writeToDestination = "dist/index.html") {
+ const bundlePath = path.resolve('dist', 'client', 'scripts', 'bundle.js')
+ const svgPath = path.resolve("src", 'deflect_logo.svg')
+ const htmlPath = path.resolve('src', 'index.html')
+
+ if (!fs.existsSync(bundlePath)) {
+ throw new Error(`Error: ${bundlePath} not found.`)
+ }
+
+ if (!fs.existsSync(htmlPath)) {
+ throw new Error(`Error: ${htmlPath} not found.`)
+ }
+
+ const bundleContent = fs.readFileSync(bundlePath, 'utf-8')
+ const svgContent = fs.existsSync(svgPath) ? fs.readFileSync(svgPath, 'utf-8') : ''
+ let htmlContent = fs.readFileSync(htmlPath, 'utf-8')
+
+ //replace the "LOGO_PLACEHOLDER" that we wrote as a comment in the index.html in src with the inlined js bundle
+ // htmlContent = htmlContent.replace(
+ // //,
+ // svgContent
+ // )
+
+ //replace the "BUNDLE_PLACEHOLDER" that we wrote as a comment in the index.html in src with the inlined js bundle
+ htmlContent = htmlContent.replace(
+ //,
+ ``
+ )
+
+ fs.writeFileSync(writeToDestination, htmlContent)
+ console.log(`Successfully inlined bundle.js and replaced logo placeholder in ${writeToDestination}`)
+}
+
diff --git a/internal/puzzle_ui/package.json b/internal/puzzle_ui/package.json
new file mode 100644
index 0000000..8117dc4
--- /dev/null
+++ b/internal/puzzle_ui/package.json
@@ -0,0 +1,56 @@
+{
+ "name": "deflectpuzzlecaptchawithrollup",
+ "version": "1.0.0",
+ "type": "module",
+ "description": "",
+ "main": "captchaRollup.config.mjs",
+ "scripts": {
+ "dev": "NODE_ENV=development npm run clean && npm run build && concurrently \"npm run watch\"",
+ "build": "npx rollup -c captchaRollup.config.mjs",
+ "clean": "rm -rf dist && mkdir dist",
+ "watch": "npx rollup -c captchaRollup.config.mjs --watch",
+ "prod": "NODE_ENV=production npm run clean && npm run build"
+ },
+ "keywords": [],
+ "author": "",
+ "license": "ISC",
+ "devDependencies": {
+ "@babel/core": "^7.26.9",
+ "@babel/preset-env": "^7.26.9",
+ "@rollup/plugin-alias": "^5.1.1",
+ "@rollup/plugin-babel": "^6.0.4",
+ "@rollup/plugin-commonjs": "^28.0.2",
+ "@rollup/plugin-node-resolve": "^16.0.0",
+ "@rollup/plugin-terser": "^0.4.4",
+ "@rollup/plugin-typescript": "^12.1.2",
+ "@types/cors": "^2.8.17",
+ "@types/crypto-js": "^4.2.2",
+ "@types/express": "^5.0.0",
+ "concurrently": "^9.1.2",
+ "cookie": "^1.0.2",
+ "glob": "^10.4.5",
+ "nodemon": "^3.1.9",
+ "postcss": "^8.5.3",
+ "rollup": "^4.34.8",
+ "rollup-plugin-obfuscator": "^1.1.0",
+ "rollup-plugin-postcss": "^4.0.2",
+ "ts-node": "^10.9.2",
+ "typescript": "^5.7.3"
+ },
+ "dependencies": {
+ "@types/pngjs": "^6.0.5",
+ "@types/validator": "^13.12.2",
+ "core-js": "^3.40.0",
+ "cors": "^2.8.5",
+ "crypto-js": "^4.2.0",
+ "dotenv": "^16.4.7",
+ "express": "^4.21.2",
+ "fast-text-encoding": "^1.0.6",
+ "js-base64": "^3.7.7",
+ "pngjs": "^7.0.0",
+ "regenerator-runtime": "^0.14.1",
+ "tsconfig-paths": "^4.2.0",
+ "tslib": "^2.8.1",
+ "validator": "^13.12.0"
+ }
+}
diff --git a/internal/puzzle_ui/src/client/scripts/attach-footer-and-header-info.ts b/internal/puzzle_ui/src/client/scripts/attach-footer-and-header-info.ts
new file mode 100644
index 0000000..cae4db8
--- /dev/null
+++ b/internal/puzzle_ui/src/client/scripts/attach-footer-and-header-info.ts
@@ -0,0 +1,34 @@
+
+/**
+ attachFooterHeaderHostname allows us to dynamically inject the footer and header hostname in to match the hostname the requester was accessing
+*/
+export default function attachFooterHeaderHostname():{success:boolean, error:Error | null} {
+
+ try {
+
+ const footerSiteName = document.querySelector(".website-title-footer")
+ const headerSiteName = document.querySelector(".website-title")
+
+ if (!footerSiteName && !headerSiteName) {
+ const errorPayload = {footer_status:footerSiteName, header_status:headerSiteName}
+ return {success:false, error:new Error(`ErrFailedToAttachHostname: ${JSON.stringify(errorPayload)}`)}
+ }
+
+ //otherwise, attach it where possible
+
+ if (footerSiteName) {
+ footerSiteName.textContent = document.location.hostname
+ }
+
+ if (headerSiteName) {
+ headerSiteName.textContent = document.location.hostname
+ }
+
+
+ return {success:true, error:null}
+
+ } catch(error) {
+ //because its most likely that you didnt provide something that could be expressed as url (ie TypeError: Failed to construct 'URL': Invalid URL)
+ return {success:false, error:new Error(`ErrCaughtException: while attachFooterHeaderHostname() ${error}`)}
+ }
+}
\ No newline at end of file
diff --git a/internal/puzzle_ui/src/client/scripts/check-initial-state.ts b/internal/puzzle_ui/src/client/scripts/check-initial-state.ts
new file mode 100644
index 0000000..8d026c5
--- /dev/null
+++ b/internal/puzzle_ui/src/client/scripts/check-initial-state.ts
@@ -0,0 +1,60 @@
+
+/**
+ checkForInitialState allows us to check for the presence of dynamically injected initial state payload such that we can cut the extra round trip out
+ it will only request state if this is not here or if the user clicks on the refresh button
+*/
+export default function checkForInitialState():{success:boolean, error:Error | null, initialState:PuzzleChallenge | null} {
+
+ try {
+ const stateElement = document.getElementById("initial-game-state")
+
+ if (!stateElement) {
+ const errorPayload = {initial_state_status:stateElement}
+ return {success:false, error:new Error(`ErrInitialStateNotFound: ${JSON.stringify(errorPayload)}`), initialState:null}
+ }
+
+
+ //to prevent parsing an empty state, we can check to see if trimming gets us to an empty string
+ const rawState = stateElement.textContent?.trim()
+ if (!rawState) {
+ return {success: false, error: new Error("ErrInitialStateEmpty"), initialState: null}
+ }
+
+ //otherwise, get the initial state, parse it and provide it to the client side solver
+ const initialState:PuzzleChallenge = JSON.parse(rawState)
+
+ if (!initialState) {
+ return {success:false, error:new Error("ErrFailedToParseInitialState"), initialState:null}
+ }
+
+ if (!isValidPuzzleChallenge(initialState)) {
+ return {success:false, error:new Error(`ErrInvalidInitialPuzzleChallenge`), initialState:null}
+ }
+
+ return {success:true, error:null, initialState:initialState}
+
+ } catch(error) {
+ return {success: false, error: new Error(`ErrCaughtException: ${error.message}\nStack: ${error.stack}`), initialState: null}
+ }
+}
+
+function isValidPuzzleChallenge(data: any): data is PuzzleChallenge {
+ return (
+ typeof data === "object" && data !== null &&
+
+ //gameBoard must be a non-empty 2D array of (TileImagePartitionValue | null)
+ Array.isArray(data.gameBoard) && data.gameBoard.length > 0 && data.gameBoard.every(row => Array.isArray(row) && row.length > 0) &&
+
+ //thumbnail_base64 must be a non-empty string
+ typeof data.thumbnail_base64 === "string" && data.thumbnail_base64.trim() !== "" &&
+
+ //maxNumberOfMovesAllowed must be a positive integer
+ typeof data.maxNumberOfMovesAllowed === "number" && data.maxNumberOfMovesAllowed > 0 &&
+
+ //timeToSolve_ms must be a positive integer
+ typeof data.timeToSolve_ms === "number" && data.timeToSolve_ms > 0 &&
+
+ //click_chain must contain exactly ONE entry at the start
+ Array.isArray(data.click_chain) && data.click_chain.length === 1
+ )
+}
diff --git a/internal/puzzle_ui/src/client/scripts/client-captcha-solver.ts b/internal/puzzle_ui/src/client/scripts/client-captcha-solver.ts
new file mode 100644
index 0000000..a3fef33
--- /dev/null
+++ b/internal/puzzle_ui/src/client/scripts/client-captcha-solver.ts
@@ -0,0 +1,776 @@
+import {stringToBase64WithFallback, clickChainToBase64WithFallback} from "./utils/b64-utils"
+import {attachCookie, getCookieValue} from "./utils/cookie-utils"
+import {generateHmacWithFallback} from "./utils/hmac-utils"
+
+
+
+
+
+
+
+
+export default class ClientCaptchaSolver {
+
+ private puzzleChallenge: PuzzleChallenge
+
+ private gameBoard:(TileImagePartitionValue | null)[][]
+
+ private maxNumberOfMovesAllowed:number
+ private clickCountTracker:number
+ private clickChain:iClickChainEntry[]
+
+ private timerId: number | null = null
+ private startTime: number = 0
+ private totalTimeAllowed: number = 0
+ // private challengeIssuedAtTime:string
+
+ private puzzleContainerElement:HTMLElement
+ private thumbnailElement: HTMLImageElement
+ private submitSolutionButton: HTMLButtonElement
+ private isSubmittingSolution:boolean
+
+
+ currentMessageTimeout: number | null = null
+
+ // private challengeDifficulty:difficulty
+
+ private tileElements: HTMLElement[][] = []
+
+ private gameplayDataCollectionEnabled:boolean
+
+ // private desiredEndpoint:string
+
+ // private VERIFY_SOLUTION_ENDPOINT:string
+ private CAPTCHA_COOKIE_NAME: string
+
+ private debug:boolean
+
+
+ constructor(puzzleChallenge: PuzzleChallenge, CAPTCHA_COOKIE_NAME:string, debug?:boolean) {
+
+ this.debug = debug ?? false
+
+ this.isSubmittingSolution = false
+
+ // this.VERIFY_SOLUTION_ENDPOINT = VERIFY_SOLUTION_ENDPOINT
+ this.CAPTCHA_COOKIE_NAME = CAPTCHA_COOKIE_NAME
+
+ this.gameBoard = puzzleChallenge.gameBoard
+
+ this.maxNumberOfMovesAllowed = puzzleChallenge.maxNumberOfMovesAllowed
+ this.clickCountTracker = 0
+
+ this.totalTimeAllowed = puzzleChallenge.timeToSolve_ms
+
+ this.puzzleChallenge = puzzleChallenge
+
+ this.gameplayDataCollectionEnabled = puzzleChallenge.collect_data
+
+ // this.desiredEndpoint = puzzleChallenge.users_intended_endpoint
+
+ // this.challengeIssuedAtTime = puzzleChallenge.challenge_issued_date
+
+ this.clickChain = puzzleChallenge.click_chain
+
+ // this.challengeDifficulty = puzzleChallenge.challenge_difficulty
+
+ const thumbnailElement = document.getElementById("deflect-puzzle-thumbnail") as HTMLImageElement | null
+ if (!thumbnailElement) {
+ throw new Error(`ErrMissingRequirement: thumnailElement`)
+ }
+ this.thumbnailElement = thumbnailElement
+
+ const puzzleContainerElement = document.getElementById('deflect-puzzle') as HTMLElement | null
+ if (!puzzleContainerElement) {
+ throw new Error(`ErrMissingRequirement: puzzleContainerElement`)
+ }
+ this.puzzleContainerElement = puzzleContainerElement
+
+ const submitSolutionButton = document.getElementById("submit-deflect-captcha-solution") as HTMLButtonElement | null
+ if (!submitSolutionButton) {
+ throw new Error(`ErrMissingRequirement: submitSolutionButton`)
+ }
+ this.submitSolutionButton = submitSolutionButton
+
+
+ //60ms debounce to prevent accidental clicks & double clicks etc
+ this.moveTile = this.debounce(this.moveTile.bind(this), 60)
+ // this.puzzleContainerElement.addEventListener("mousedown", this.moveTile)
+ //we attach it in such a way that if something is thrown we can bubble it back to the entry point to exploit the retry/fallback
+ this.puzzleContainerElement.addEventListener("mousedown", async (event) => {
+ try {
+ await this.moveTile(event)
+ } catch (error) {
+ console.error(`Error bubbled to top level: ${error}`);
+ // throw new Error(`ErrCaughtException: moveTile event listener: ${error}`)
+ window.dispatchEvent(new CustomEvent("captchaError", {detail: error}))
+ }
+ })
+
+
+
+ //no debounce on submit since we have a function guard. When submission starts we immediately set it to true
+ //and only set it back to false (allowing another submission) when the previous submission completes
+ this.submitSolution = this.submitSolution.bind(this)
+ this.submitSolutionButton.addEventListener("click", this.submitSolution)
+ }
+
+
+ initCaptcha():{success:boolean, error:Error | null} {
+
+ try {
+
+ //check for missing requirements
+ if (this.thumbnailElement === null || !this.thumbnailElement) {
+ return {success:false, error: new Error(`ErrMissingThumbnail: expected HTMLImageElement, got: type: ${typeof this.thumbnailElement} - ${this.thumbnailElement}`)}
+ }
+
+ if (this.puzzleContainerElement === null || !this.puzzleContainerElement) {
+ return {success:false, error: new Error(`ErrMissingPuzzleContainer: expected HTMLElement, got: type: ${typeof this.puzzleContainerElement} - ${this.puzzleContainerElement}`)}
+ }
+
+ //at this point we know we have access to all elements needed to run challenge
+
+ //figure out the dimensions of the puzzle user is meant to solve and apply the css grid styling required
+ const rows = this.puzzleChallenge.gameBoard.length
+ const columns = this.puzzleChallenge.gameBoard[0].length
+
+ //set the thumbnail image
+ //we cannot apply the grid directly to the
+
+
+
+ Recreate this image by selecting which squares to move
+ +
+
+
+
+ ![Complete Puzzle]()
+
+
+
+
+
+
+ ×
+ ![]()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ×
+
+
+
+
+ Rearrange the tiles to match the thumbnail.
+ +Click on Tiles Adjacent to the Empty Space:
+ +- Only tiles directly next to the empty slot can be moved.
+- Click on a tile to slide it into the empty space.
+ +Recreate the Full Image:
+ +- Keep moving the tiles until the image is complete, matching the reference.
+- Pay attention to the details—logos, text, and shapes must align.
+
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/internal/puzzle_ui/tsconfig.json b/internal/puzzle_ui/tsconfig.json
new file mode 100644
index 0000000..3e85e0e
--- /dev/null
+++ b/internal/puzzle_ui/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "types": ["./types/shared"],
+ "module": "ESNext",
+ //we set target ES5 for legacy support
+ "target": "ES5",
+ "moduleResolution": "node",
+ "lib": ["ES5", "ES2015", "ES2016", "ES2017", "ES2018", "ES2019", "DOM"],
+ "esModuleInterop": true,
+ "allowSyntheticDefaultImports": true,
+ "baseUrl": "./src",
+ "outDir": "./dist",
+ "skipLibCheck": true
+ },
+ "include": ["src/**/*", "types/**/*"]
+}
\ No newline at end of file
diff --git a/internal/puzzle_ui/types/shared.d.ts b/internal/puzzle_ui/types/shared.d.ts
new file mode 100644
index 0000000..42eb911
--- /dev/null
+++ b/internal/puzzle_ui/types/shared.d.ts
@@ -0,0 +1,46 @@
+
+export {}
+
+declare global {
+
+ //click chain entry tile properties
+ interface iTileProperties {
+ id:string
+ row:number
+ col:number
+ }
+
+ //interface for the client chain type
+ interface iClickChainEntry {
+ time_stamp:string
+ tile_clicked: iTileProperties
+ tile_swapped_with: iTileProperties
+
+ click_count:number
+ hash:string
+ }
+
+ //data we are collecting for submission
+ interface iClientSolutionSubmissionPayload {
+ solution:string
+ click_chain:iClickChainEntry[]
+ }
+
+ /* client side game board item satisfies the following */
+ type TileImagePartitionValue = {
+ base64_image: string
+ tile_grid_id: string
+ }
+
+ //the interface that describes the shape the the CAPTCHA challenge payload we send to users
+ interface PuzzleChallenge {
+ gameBoard:(TileImagePartitionValue | null)[][]
+ thumbnail_base64:string
+ maxNumberOfMovesAllowed:number
+ timeToSolve_ms:number
+ collect_data:boolean
+ click_chain:iClickChainEntry[]
+ }
+
+}
+
diff --git a/internal/puzzle_verifier.go b/internal/puzzle_verifier.go
new file mode 100644
index 0000000..3ec8d15
--- /dev/null
+++ b/internal/puzzle_verifier.go
@@ -0,0 +1,231 @@
+package internal
+
+import (
+ "crypto/subtle"
+ "errors"
+ "fmt"
+ "time"
+)
+
+type ClientPuzzleSolutionSubmissionPayload struct {
+ Solution string `json:"solution"`
+ ClickChain []ClickChainEntry `json:"click_chain"`
+}
+
+var (
+ ErrInvalidGenesisClickChainEntry = errors.New("submitted click chain entry does not match expectation")
+ ErrCookieDeleteOrNeverExisted = errors.New("solution was either submitted too late so the cookie was deleted or never existed")
+ ErrFailedClickChainIntegrity = errors.New("failed click chain integrity check")
+ ErrFailedCaptchaPropertiesIntegrity = errors.New("failed captcha properties integrity check")
+ ErrFailedGameboardIntegrity = errors.New("failed game board integrity check")
+ ErrVerificationFailedTimeLimit = errors.New("submitted solution failed time limit check")
+ ErrVerificationFailedClickLimit = errors.New("submitted solution failed click limit check")
+ ErrVerificationFailedBoardTiles = errors.New("submitted solution failed board tiles check")
+ ErrVerificationFailedSolutionHash = errors.New("submitted solution failed hash check")
+ ErrRecreatingTileMap = errors.New("failed to recreate tile map for validation")
+ ErrRecreating = errors.New("failed to recreate the puzzle that gave rise to the solution")
+)
+
+/*
+VerifySolution verifies the solution payload submitted by the user.
+
+The solution is a hash and integrity/anti-cheat is a click chain (similar to how a blockchain works) that we integrity check and verify.
+
+After the integrity check of the click chain is complete we can trust the timestamp embedded into the genesis click chain item
+as well as the users challenge cookie string value being the one we issued to them to complete this challenge in particular because:
+ 1. The genesis click chain item was created using the challenge cookie and
+ 2. their original TileIDs were re-computed using their cookie value which would not produce the correct tileIDs and subsequently solution otherwise
+
+NOTE:
+Technically, this is just 1/2 of the solution. We are also meant to collect data about how the
+game was played and make a prediction about bot or not as the hypothesis behind state the "state-space search problem"
+puzzle was that bots and people would play the game differently. Regardless, we need to make sure that the solution
+itself is indeed correct and we do so with a call to VerifySolution
+*/
+func ValidatePuzzleCAPTCHASolution(config *Config, puzzleImageController *PuzzleImageController, userChallengeCookieString string, userCaptchaSolution ClientPuzzleSolutionSubmissionPayload) error {
+
+ //we need to derive a solution to their challenge, and recompute their shuffled & unshuffled board
+ var shuffledBoard [][]*PuzzleTileWithoutImage
+ var unshuffledBoard [][]*PuzzleTileWithoutImage
+ var expectedSolution string
+ var err error
+ shuffledBoard, unshuffledBoard, expectedSolution, err = GeneratePuzzleExpectedSolution(config, puzzleImageController, userChallengeCookieString)
+ if err != nil {
+ return fmt.Errorf("%w: %v", ErrRecreating, err)
+ }
+
+ if shuffledBoard == nil || unshuffledBoard == nil || expectedSolution == "" {
+ return fmt.Errorf("%w: %v", ErrRecreating, errors.New("one or more generated outputs were invalid"))
+ }
+
+ //at this point we have recomputed everything, we can now perform the integrity check on the click chain as well as the time limit, click limit and solution checks
+
+ //integrity checks
+
+ err = IntegrityCheckPuzzleClickChain(userCaptchaSolution.Solution, userChallengeCookieString, config.PuzzleClickChainEntropySecret, userCaptchaSolution.ClickChain, shuffledBoard, unshuffledBoard)
+ if err != nil {
+ return fmt.Errorf("%w: %v", ErrFailedClickChainIntegrity, err)
+ }
+
+ //constraints & solutions checks
+
+ err = verifyPuzzleTimeLimit(config, userCaptchaSolution.ClickChain, userChallengeCookieString)
+ if err != nil {
+ return fmt.Errorf("%w: %v", ErrVerificationFailedTimeLimit, err)
+ }
+
+ err = verifyPuzzleClickLimit(config, userCaptchaSolution.ClickChain, userChallengeCookieString)
+ if err != nil {
+ return fmt.Errorf("%w: %v", ErrVerificationFailedClickLimit, err)
+ }
+
+ err = VerifyPuzzleSolutionHash(userCaptchaSolution.Solution, expectedSolution)
+ if err != nil {
+ return fmt.Errorf("%w: %v", ErrVerificationFailedBoardTiles, err)
+ }
+
+ return nil
+}
+
+func GeneratePuzzleExpectedSolution(config *Config, puzzleImageController *PuzzleImageController, userChallengeCookieString string) (shuffledBoard [][]*PuzzleTileWithoutImage, unshuffledBoard [][]*PuzzleTileWithoutImage, expectedSolution string, err error) {
+
+ includeB64ImageData := false // dont need b64 image data when verifying the solution
+ var tileMap PuzzleTileMap[PuzzleTileWithoutImage]
+
+ tileMap, err = PuzzleTileMapFromImage[PuzzleTileWithoutImage](config, puzzleImageController, userChallengeCookieString, includeB64ImageData)
+ if err != nil {
+ err = fmt.Errorf("%w: %v", ErrRecreatingTileMap, err)
+ return
+ }
+
+ var exists bool
+ targetDifficulty, exists := PuzzleDifficultyProfileByName(config, config.PuzzleDifficultyTarget, userChallengeCookieString)
+ if !exists {
+ err = ErrTargetDifficultyDoesNotExist
+ return
+ }
+
+ shuffledBoard, err = NewPuzzleCAPTCHABoard(tileMap, targetDifficulty)
+ if err != nil {
+ err = fmt.Errorf("%w: %v", ErrFailedNewCAPTCHAGeneration, err)
+ return
+ }
+
+ // Note: We need to remove the tile prior to making a deep copy such that both shuffled and unshuffled boards have the null tile as needed for validation.
+ if err = RemovePuzzleTileFromBoard(shuffledBoard, targetDifficulty); err != nil {
+ err = fmt.Errorf("%w: %v", ErrFailedRemovingTile, err)
+ return
+ }
+
+ unshuffledBoard, err = DeepCopyPuzzleTileBoard(shuffledBoard)
+ if err != nil {
+ err = fmt.Errorf("%w: %v", ErrFailedNewGameboard, err)
+ return
+ }
+
+ nReShuffles := 0
+ if err = ShufflePuzzleBoard(shuffledBoard, unshuffledBoard, targetDifficulty, nReShuffles, config.PuzzleEntropySecret, userChallengeCookieString); err != nil {
+ err = fmt.Errorf("%w: %v", ErrFailedShuffling, err)
+ return
+ }
+
+ expectedSolution = CalculateExpectedPuzzleSolution(unshuffledBoard, userChallengeCookieString)
+
+ return
+}
+
+func verifyPuzzleTimeLimit(config *Config, submittedClickChain []ClickChainEntry, userChallengeCookieString string) error {
+
+ //every click chain will at least admit the genesis block
+ if len(submittedClickChain) == 0 {
+ return errors.New("ErrExpectedAtLeastGenesisBlock")
+ }
+
+ //we do not issue challenges that have not been shuffled
+ if len(submittedClickChain) == 1 {
+ return errors.New("ErrExpectedAtleastOneClickRequiredToSolve")
+ }
+
+ genesisChainEntryIssuedAtTime := submittedClickChain[0].TimeStamp
+
+ dateOfIssuanceByClickChain, err := isValidISOString(genesisChainEntryIssuedAtTime)
+ if err != nil {
+ return fmt.Errorf("ErrFailedToParseData: Expected date of issuance from click chain to be valid ISO 3399 compliant string, got: %s", genesisChainEntryIssuedAtTime)
+ }
+
+ difficultyProfile, exists := PuzzleDifficultyProfileByName(config, config.PuzzleDifficultyTarget, userChallengeCookieString)
+ if !exists {
+ return ErrTargetDifficultyDoesNotExist
+ }
+
+ //now compare the time it was issued with the time we get from the challenge difficulty to know whether or not they actually exceeded the time limit
+ maxTimeAllowed := time.Duration(difficultyProfile.TimeToSolveMs) * time.Millisecond
+
+ //adjust issuedAtDate by the allowed solving time in order to compare to nowTime
+ expiryTime := dateOfIssuanceByClickChain.Add(maxTimeAllowed)
+
+ //we account for potential network/processing delay by adding 2 seconds (2000 ms) to nowTime
+ now := time.Now().Add(2 * time.Second)
+
+ if now.After(expiryTime) {
+ return fmt.Errorf("ErrTimeExpired: Expected puzzle (issued at: %s) to be solved within: %d ms (by: %s), but received result at: %s", dateOfIssuanceByClickChain, difficultyProfile.TimeToSolveMs, expiryTime, now)
+ }
+
+ return nil
+}
+
+func verifyPuzzleClickLimit(config *Config, submittedClickChain []ClickChainEntry, userChallengeCookieString string) error {
+
+ //every click chain will at least admit the genesis block
+ if len(submittedClickChain) == 0 {
+ return errors.New("ErrExpectedAtLeastGenesisBlock")
+ }
+
+ //we do not issue challenges that have not been shuffled
+ if len(submittedClickChain) == 1 {
+ return errors.New("ErrExpectedAtleastOneClickRequiredToSolve")
+ }
+
+ difficultyProfile, exists := PuzzleDifficultyProfileByName(config, config.PuzzleDifficultyTarget, userChallengeCookieString)
+ if !exists {
+ return ErrTargetDifficultyDoesNotExist
+ }
+
+ //click chain will contain the genesis, so we account for it by subtracting by 1 to make sure that the number of clicks is indeed within allowed limit
+ nClicksMade := len(submittedClickChain) - 1
+
+ if nClicksMade > difficultyProfile.MaxNumberOfMovesAllowed {
+ return fmt.Errorf("ErrClickLimitExceeded: expected nClicksMade: %d < maximum allowed number of clicks to solve puzzle: %d", nClicksMade, difficultyProfile.MaxNumberOfMovesAllowed)
+ }
+
+ return nil
+}
+
+/*
+because "==" leaks info that can be used for timing attacks (users can just keep making strings bigger and bigger to see how it behaves)
+we use crypto.subtle's ConstantTimeCompare
+*/
+func VerifyPuzzleSolutionHash(userSubmittedSolution, locallyStoredPrecomputedSolution string) error {
+
+ solutionA := []byte(userSubmittedSolution)
+ solutionB := []byte(locallyStoredPrecomputedSolution)
+
+ if len(solutionA) != len(solutionB) {
+ return fmt.Errorf("ErrInvalidSolution: Solutions have different lengths")
+ }
+
+ if subtle.ConstantTimeCompare(solutionA, solutionB) == 1 {
+ return nil
+ }
+
+ return fmt.Errorf("ErrInvalidSolution: Expected %s, received %s", locallyStoredPrecomputedSolution, userSubmittedSolution)
+}
+
+/*checks if dateString provided as argument is ISO 8601 timestamp*/
+func isValidISOString(dateString string) (time.Time, error) {
+ parsedTime, err := time.Parse(time.RFC3339, dateString)
+ if err != nil {
+ return time.Time{}, errors.New("invalid ISO 8601 date string")
+ }
+ return parsedTime, nil
+}
diff --git a/internal/regex_rate_limiter_test.go b/internal/regex_rate_limiter_test.go
index c0e82a0..bed8cae 100644
--- a/internal/regex_rate_limiter_test.go
+++ b/internal/regex_rate_limiter_test.go
@@ -25,7 +25,8 @@ import (
)
type MockBanner struct {
- bannedIp string
+ bannedIp string
+ banTimeSeconds int
}
// XXX confused why this (with a pointer receiver) and the one in iptables.go
@@ -58,19 +59,32 @@ func (mb *MockBanner) LogRegexBan(
// log.Printf("LogRegexBan: %s %s %s\n", ip, ruleName, logLine)
}
+func (mb *MockBanner) OverwriteBanWithRateLimit(config *Config, ip string, banTimeSeconds int) {
+ mb.bannedIp = ip
+ mb.banTimeSeconds = banTimeSeconds
+}
+
func (mb *MockBanner) IPSetAdd(config *Config, ip string) error {
+ mb.bannedIp = ip
return nil
}
func (mb *MockBanner) IPSetTest(config *Config, ip string) bool {
- return false
+ //simulate whether an ip is already banned
+ return mb.bannedIp == ip
}
func (mb *MockBanner) IPSetList() (*ipset.Info, error) {
return nil, nil
}
+// to simulate removing as we do in the context of overwrite
func (mb *MockBanner) IPSetDel(ip string) error {
+ // Simulate removing the ban
+ if mb.bannedIp == ip {
+ mb.bannedIp = ""
+ mb.banTimeSeconds = 0
+ }
return nil
}
@@ -377,3 +391,29 @@ func TestMarshalRateLimitMatchType(t *testing.T) {
assert.Equal(t, expected, string(json))
}
}
+
+func TestOverwriteBanWithRateLimit(t *testing.T) {
+ config := Config{
+ StandaloneTesting: false, //make sure we are not skipping bans in test mode
+ }
+ mockBanner := MockBanner{}
+
+ //this is the first ban attempt
+ ip := "192.168.1.1"
+ mockBanner.OverwriteBanWithRateLimit(&config, ip, 30)
+
+ //make sure that the ip is banned for the right amount of time
+ assert.Equal(t, ip, mockBanner.bannedIp, "Expected IP to be banned")
+ assert.Equal(t, 30, mockBanner.banTimeSeconds, "Expected ban duration to be 30 seconds")
+
+ //try to ban the SAME ip again but with a different duration
+ mockBanner.OverwriteBanWithRateLimit(&config, ip, 60)
+
+ //confirm that this actually went through as desired (ie was overwritten)
+ assert.Equal(t, 60, mockBanner.banTimeSeconds, "Expected ban duration to update to 60 seconds")
+
+ //remove the ban and check that it resets as desired
+ mockBanner.IPSetDel(ip)
+ assert.Equal(t, "", mockBanner.bannedIp, "Expected IP to be unbanned")
+ assert.Equal(t, 0, mockBanner.banTimeSeconds, "Expected ban duration to reset")
+}
diff --git a/internal/static/images/default_baskerville_logo.png b/internal/static/images/default_baskerville_logo.png
new file mode 100644
index 0000000..388ebfe
Binary files /dev/null and b/internal/static/images/default_baskerville_logo.png differ
diff --git a/supporting-containers/nginx/nginx.conf b/supporting-containers/nginx/nginx.conf
index ff47b7d..e1f38e6 100644
--- a/supporting-containers/nginx/nginx.conf
+++ b/supporting-containers/nginx/nginx.conf
@@ -5,6 +5,19 @@ events {
}
http {
+
+ #in order to allow large headers through for the puzzle submission
+ #nginx allows up to 4 buggers @ 32kb each before rejecting w/ 400
+ client_header_buffer_size 16k;
+ large_client_header_buffers 4 32k;
+ # client_header_buffer_size 32k;
+ # large_client_header_buffers 4 64k;
+
+
+ #we have a rate limit for the request new puzzle and error logging endpoints which allow
+ #5 requests per second, burst up to 5 & allocate 10 megabytes of memory for tracking)
+ limit_req_zone $binary_remote_addr zone=puzzle_ratelimit:10m rate=5r/s;
+
# init var by map
map $host $banjax_decision {
default "-";
@@ -101,12 +114,45 @@ http {
proxy_pass http://test-origin:8080;
}
+ #when user asks for a refresh on a new puzzle state, or if the entrypoint script needs to report
+ #any non critical event listener failure (error), they can contact us on /__banjax/
+ #we rate limit this endpoint in 2 ways:
+ #The first is using Nginx directives to control burstiness. If they exceed the stated burst rate we return 429.
+ #The second relies on using the throttled banjax function which will ban them for 60 seconds.
+ location /__banjax/ {
+
+ #nodelay is used such that if an IP sends 5 requests instantly (burst), all are processed immediately.
+ limit_req zone=puzzle_ratelimit burst=5 nodelay;
+ limit_req_status 429;
+ add_header Retry-After 1 always;
+ error_page 429 = @access_ratelimited;
+ satisfy any;
+
+ set $loc_in "slash_block";
+ proxy_intercept_errors on;
+ error_page 500 @fail_open;
+ error_page 502 @fail_open;
+ proxy_cache_key "$remote_addr $host $cookie_deflect_challenge4";
+ proxy_set_header X-Requested-Host $host;
+ proxy_set_header X-Client-IP $remote_addr;
+ proxy_set_header X-Requested-Path $request_uri;
+ proxy_set_header X-Client-User-Agent $http_user_agent;
+ proxy_pass_request_body off;
+ proxy_pass http://127.0.0.1:8081/__banjax/;
+ }
+
+ #for nginx ratelimiting
+ location @access_ratelimited {
+ return 429 "Too many failed attempts.";
+ }
+
+
location / {
set $loc_in "slash_block";
proxy_intercept_errors on;
error_page 500 @fail_open;
error_page 502 @fail_open;
- proxy_cache_key "$remote_addr $host $cookie_deflect_challenge3";
+ proxy_cache_key "$remote_addr $host $cookie_deflect_challenge3 $cookie_deflect_challenge4";
proxy_set_header X-Requested-Host $host;
proxy_set_header X-Client-IP $remote_addr;
proxy_set_header X-Requested-Path $request_uri;
@@ -123,6 +169,24 @@ http {
return 403 "access denied";
}
+ #for banjax rate limiting - ie as determined internally but the more flexible time
+ location @access_throttled {
+ set $loc_out "access_throttled";
+ set $banjax_decision "$upstream_http_x_banjax_decision";
+ set $deflect_session "$upstream_http_x_deflect_session";
+ set $deflect_session_new "$upstream_http_x_deflect_session_new";
+
+ # Capture and use the throttle message from upstream headers
+ set $throttle_msg "Too many failed attempts. Please try again later."; # Default fallback
+
+ if ($upstream_http_x_throttle_message) {
+ set $throttle_msg "$upstream_http_x_throttle_message";
+ }
+
+ return 429 "$throttle_msg";
+ }
+
+
location @access_granted {
set $loc_out "access_granted";
set $banjax_decision "$upstream_http_x_banjax_decision";
+
+
+
+ Recreate this image by selecting which squares to move
+ +
+
+
+
+ ![Complete Puzzle]()
+
+
+
+
+
+
+ ×
+ ![]()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ×
+
+
+
+
+ Rearrange the tiles to match the thumbnail.
+ +Click on Tiles Adjacent to the Empty Space:
+ +- Only tiles directly next to the empty slot can be moved.
+- Click on a tile to slide it into the empty space.
+ +Recreate the Full Image:
+ +- Keep moving the tiles until the image is complete, matching the reference.
+- Pay attention to the details—logos, text, and shapes must align.
+
+
+
+
+