\n Server-side session management, analysis, and token verification for 007captcha.\n
\n\n
\n \n \n
\n\n---\n\nHandles everything security-sensitive: challenge generation, behavioral analysis, scoring, and HMAC-SHA256 token signing. The client widget acts as a thin rendering layer — all verification logic runs here.\n\n**Zero runtime dependencies.** Uses only Node.js built-in `crypto`.\n\n## Installation\n\n```bash\npnpm add @007captcha/server\n```\n\n## Token Verification\n\nVerify signed tokens from any challenge method:\n\n```ts\nimport { verify } from '@007captcha/server';\n\nconst result = await verify(token, SECRET);\n\nif (result.success) {\n // Allow the request\n}\n```\n\n### `verify(token, secretKey): Promise`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `success` | `boolean` | `true` if valid signature and not flagged as bot |\n| `score` | `number` | 0.0 (bot) to 1.0 (human) |\n| `method` | `string` | `'shape'`, `'maze'`, or `'ball'` |\n| `challenge` | `string` | Specific challenge identifier |\n| `verdict` | `string` | `'human'`, `'uncertain'`, or `'bot'` |\n| `timestamp` | `number` | When the challenge was completed |\n| `error` | `string?` | Reason if verification failed |\n\nTokens are single-use and expire after 5 minutes.\n\n## Challenge Managers\n\nEach challenge method has a session manager that handles the full lifecycle: session creation, challenge delivery, input analysis, and token signing. Create one instance per server process.\n\n### Ball — `BallChallengeManager`\n\nThe ball challenge generates a physics-based trajectory in real-time and streams rendered frames to the client via SSE. After the challenge, the user's cursor path is analyzed against the recorded trajectory.\n\n```ts\nimport { BallChallengeManager } from '@007captcha/server';\nconst ball = new BallChallengeManager(SECRET);\n```\n\n**Endpoints required:**\n\n| Method | Path | Handler |\n|--------|------|---------|\n| `POST` | `/captcha/ball/start` | `ball.createSession()` |\n| `GET` | `/captcha/ball/:id/stream` | `ball.startStreaming(id, onFrame, onEnd)` |\n| `POST` | `/captcha/ball/:id/verify` | `ball.verify(id, points, cursorStartT, origin)` |\n\n### Maze — `MazeChallengeManager`\n\nGenerates a procedural maze, renders it as a PNG, and solves it server-side. The client receives only the image and zone coordinates. Cursor path analysis runs entirely on the server.\n\n```ts\nimport { MazeChallengeManager } from '@007captcha/server';\nconst maze = new MazeChallengeManager(SECRET);\n```\n\n**Endpoints required:**\n\n| Method | Path | Handler |\n|--------|------|---------|\n| `POST` | `/captcha/maze/start` | `maze.createSession()` |\n| `POST` | `/captcha/maze/:id/verify` | `maze.verify(id, points, origin)` |\n\n### Shape — `ShapeChallengeManager`\n\nAssigns a random shape (circle, triangle, or square) and analyzes the user's drawing server-side. The client only knows which shape to draw — scoring and detection run here.\n\n```ts\nimport { ShapeChallengeManager } from '@007captcha/server';\nconst shape = new ShapeChallengeManager(SECRET);\n```\n\n**Endpoints required:**\n\n| Method | Path | Handler |\n|--------|------|---------|\n| `POST` | `/captcha/shape/start` | `shape.createSession()` |\n| `POST` | `/captcha/shape/:id/verify` | `shape.verify(id, points, origin)` |\n\n## Express Integration\n\nFull working example with all three methods:\n\n```js\nimport express from 'express';\nimport {\n verify,\n BallChallengeManager,\n MazeChallengeManager,\n ShapeChallengeManager,\n} from '@007captcha/server';\n\nconst app = express();\nconst SECRET = process.env.CAPTCHA_SECRET;\n\nconst ball = new BallChallengeManager(SECRET);\nconst maze = new MazeChallengeManager(SECRET);\nconst shape = new ShapeChallengeManager(SECRET);\n\napp.use(express.json());\n\n// Ball\napp.post('/captcha/ball/start', (req, res) => {\n res.json(ball.createSession());\n});\n\napp.get('/captcha/ball/:id/stream', (req, res) => {\n res.writeHead(200, {\n 'Content-Type': 'text/event-stream',\n 'Cache-Control': 'no-cache',\n Connection: 'keep-alive',\n });\n let done = false;\n const ok = ball.startStreaming(\n req.params.id,\n (frame) => res.write(`event: frame\\ndata: ${JSON.stringify(frame)}\\n\\n`),\n () => { done = true; res.write('event: end\\ndata: {}\\n\\n'); res.end(); },\n );\n if (!ok) { res.end(); return; }\n req.on('close', () => { if (!done) ball.cancelSession(req.params.id); });\n});\n\napp.post('/captcha/ball/:id/verify', (req, res) => {\n const { points, cursorStartT, origin } = req.body;\n res.json(ball.verify(req.params.id, points || [], cursorStartT || 0, origin || ''));\n});\n\n// Maze\napp.post('/captcha/maze/start', (req, res) => res.json(maze.createSession()));\napp.post('/captcha/maze/:id/verify', (req, res) => {\n res.json(maze.verify(req.params.id, req.body.points || [], req.body.origin || ''));\n});\n\n// Shape\napp.post('/captcha/shape/start', (req, res) => res.json(shape.createSession()));\napp.post('/captcha/shape/:id/verify', (req, res) => {\n res.json(shape.verify(req.params.id, req.body.points || [], req.body.origin || ''));\n});\n\n// Token verification\napp.post('/verify', async (req, res) => {\n res.json(await verify(req.body.token || '', SECRET));\n});\n\napp.listen(3007);\n```\n\nSee [`examples/express-server/`](../../examples/express-server/) for the full demo with a UI.\n\n## Session Lifecycle\n\n- Sessions are stored in memory and auto-expire (60s for ball/shape, 120s for maze).\n- Each session can only be verified once.\n- Call `manager.destroy()` on server shutdown to clean up timers.\n- For horizontally scaled deployments, sessions are per-process — route challenge requests to the same instance (sticky sessions or a shared store).\n\n## License\n\n[MIT](../../LICENSE)\n","readmeFilename":"README.md","_rev":"1-f93081998657fafd1a63cd0fe8d37f8a"}
![\"007captcha\"](\"../../007-logo.png\"){kind=logo}
\n![\"npm\"](\"https://img.shields.io/npm/v/@007captcha/server?color=111827\")
![\"license\"](\"https://img.shields.io/github/license/mutkuoz/007captcha?color=111827\")