3D Shape CAPTCHA
A click-based geometric CAPTCHA system with real-time 3D rendering, multi-light shadows, and proportional scale generation guaranteeing 6 unique sizes.
Architecture
Backend (Go) Frontend (Vue3 + Three.js)
| |
Generate 6 shape Render WebGL scene
metadata (no PNG) with shadows
| |
Store in Redis <--- Raycaster click
| detects object
Validate shapeIndex |
| |
Issue token ---------> Success
Backend generates scene metadata only. Frontend renders the actual 3D scene with Three.js. User clicks are validated by object index, not pixel coordinates.
Backend Implementation
Core Files
assets/backend-captcha.go — Complete Go implementation (captcha generation + verification)references/backend-api.md — API specification, data models, Redis schema, scale algorithm
Key Design Decisions
- No PNG rendering — Backend returns JSON metadata; frontend handles all visuals
- Proportional scale — 6 shapes generated from a scale
[0.55, 1.30] with equal-interval base values plus ±0.03 jitter. Base interval (0.15) > 2× jitter range (0.06) mathematically guarantees all 6 scales are unique
- Grid layout — 2×3 grid with ±0.4 random offset within each cell prevents overlap
- Volume comparison — Uses
scale³ as uniform metric regardless of shape type
Redis Schema
| Key |
Value |
TTL |
captcha:{id} |
JSON: {targetIndex, shapes[], prompt, targetShape} |
5 min |
captcha_token:{token} |
"1" |
5 min |
Integration Points
POST /api/captcha/generate — Returns 6 shape metadataPOST /api/captcha/verify — Receives {captchaId, shapeIndex}, returns token on successValidateCaptchaToken(redis, token) — Utility for other controllers (e.g. email verification)
Frontend Implementation
Core Files
assets/CaptchaDialog.vue — Complete Vue3 component with Three.js sceneassets/api-index.js — API client functionsreferences/frontend-integration.md — Scene setup, lighting config, raycaster, responsive CSS
Three.js Scene Setup
| Component |
Configuration |
| Renderer |
WebGLRenderer, antialias, shadowMap enabled, PCFSoftShadowMap |
| Camera |
OrthographicCamera (frustumSize=7.5), position (8,8,8), lookAt (0,0.5,0) |
| Lights |
Ambient(0.35) + Hemisphere(0.4) + Directional(1.4, casts shadow) + Fill(0.25) + Rim Point(0.4) |
| Ground |
PlaneGeometry(20,20), MeshStandardMaterial, receiveShadow |
| Material |
MeshStandardMaterial, roughness=0.35, metalness=0.08 |
Shape Geometry Mapping
type |
Shape |
Three.js Geometry |
| 0 |
Cube |
BoxGeometry(1,1,1) |
| 1 |
Cylinder |
CylinderGeometry(0.5,0.5,1,32) |
| 2 |
Triangular prism |
CylinderGeometry(0.5,0.5,1.25,3) |
Triangular prism uses height 1.25 (vs 1.0 for others) for better visual distinction.
Click Interaction
Use THREE.Raycaster to detect clicked mesh. Each mesh stores its index in userData.index. Send this index to backend for verification.
Responsive Design
- Desktop: dialog max-width 520px, canvas height 360px
- Mobile (<480px): canvas height 260px
- Mobile (<360px): canvas height 220px
Workflow: Adding CAPTCHA to Email Verification
- Backend: Add
captchaToken field to email send request
- Backend: Call
captcha.ValidateCaptchaToken(redis, token) before sending email
- Frontend: Open
CaptchaDialog before requesting email code
- Frontend: On
success event, receive token and include it in email API call
Complete Code References
- Backend implementation:
assets/backend-captcha.go
- Frontend dialog component:
assets/CaptchaDialog.vue
- API functions:
assets/api-index.js
- Backend API details:
references/backend-api.md
- Frontend integration guide:
references/frontend-integration.md
1---2name: 3d-shape-captcha3description: 基于 Three.js 实时渲染的 3D 几何体验证码系统，支持软阴影和 Raycaster 点击交互。后端生成 6 个大小严格互不相同的 3D 几何体元数据（位置、旋转、缩放、颜色、类型），前端使用多光源布光和正交相机实现公平大小比较。适用于实现或修改基于点击的 3D 几何体验证码，或将图形验证码集成到邮件验证码发送等敏感操作中。4---56# 3D Shape CAPTCHA78A click-based geometric CAPTCHA system with real-time 3D rendering, multi-light shadows, and proportional scale generation guaranteeing 6 unique sizes.910## Architecture1112```13Backend (Go) Frontend (Vue3 + Three.js)14 | |15Generate 6 shape Render WebGL scene16metadata (no PNG) with shadows17 | |18Store in Redis <--- Raycaster click19 | detects object20Validate shapeIndex |21 | |22Issue token ---------> Success23```2425Backend generates scene metadata only. Frontend renders the actual 3D scene with Three.js. User clicks are validated by object index, not pixel coordinates.2627## Backend Implementation2829### Core Files3031- `assets/backend-captcha.go` — Complete Go implementation (captcha generation + verification)32- `references/backend-api.md` — API specification, data models, Redis schema, scale algorithm3334### Key Design Decisions35361. **No PNG rendering** — Backend returns JSON metadata; frontend handles all visuals372. **Proportional scale** — 6 shapes generated from a scale `[0.55, 1.30]` with equal-interval base values plus ±0.03 jitter. Base interval (0.15) > 2× jitter range (0.06) mathematically guarantees all 6 scales are unique383. **Grid layout** — 2×3 grid with ±0.4 random offset within each cell prevents overlap394. **Volume comparison** — Uses `scale³` as uniform metric regardless of shape type4041### Redis Schema4243| Key | Value | TTL |44|---|---|---|45| `captcha:{id}` | JSON: `{targetIndex, shapes[], prompt, targetShape}` | 5 min |46| `captcha_token:{token}` | `"1"` | 5 min |4748### Integration Points4950- `POST /api/captcha/generate` — Returns 6 shape metadata51- `POST /api/captcha/verify` — Receives `{captchaId, shapeIndex}`, returns token on success52- `ValidateCaptchaToken(redis, token)` — Utility for other controllers (e.g. email verification)5354## Frontend Implementation5556### Core Files5758- `assets/CaptchaDialog.vue` — Complete Vue3 component with Three.js scene59- `assets/api-index.js` — API client functions60- `references/frontend-integration.md` — Scene setup, lighting config, raycaster, responsive CSS6162### Three.js Scene Setup6364| Component | Configuration |65|---|---|66| Renderer | WebGLRenderer, antialias, shadowMap enabled, PCFSoftShadowMap |67| Camera | OrthographicCamera (frustumSize=7.5), position (8,8,8), lookAt (0,0.5,0) |68| Lights | Ambient(0.35) + Hemisphere(0.4) + Directional(1.4, casts shadow) + Fill(0.25) + Rim Point(0.4) |69| Ground | PlaneGeometry(20,20), MeshStandardMaterial, receiveShadow |70| Material | MeshStandardMaterial, roughness=0.35, metalness=0.08 |7172### Shape Geometry Mapping7374| `type` | Shape | Three.js Geometry |75|---|---|---|76| 0 | Cube | `BoxGeometry(1,1,1)` |77| 1 | Cylinder | `CylinderGeometry(0.5,0.5,1,32)` |78| 2 | Triangular prism | `CylinderGeometry(0.5,0.5,1.25,3)` |7980Triangular prism uses height 1.25 (vs 1.0 for others) for better visual distinction.8182### Click Interaction8384Use `THREE.Raycaster` to detect clicked mesh. Each mesh stores its index in `userData.index`. Send this index to backend for verification.8586### Responsive Design8788- Desktop: dialog max-width 520px, canvas height 360px89- Mobile (<480px): canvas height 260px90- Mobile (<360px): canvas height 220px9192## Workflow: Adding CAPTCHA to Email Verification93941. **Backend**: Add `captchaToken` field to email send request952. **Backend**: Call `captcha.ValidateCaptchaToken(redis, token)` before sending email963. **Frontend**: Open `CaptchaDialog` before requesting email code974. **Frontend**: On `success` event, receive token and include it in email API call9899## Complete Code References100101- Backend implementation: `assets/backend-captcha.go`102- Frontend dialog component: `assets/CaptchaDialog.vue`103- API functions: `assets/api-index.js`104- Backend API details: `references/backend-api.md`105- Frontend integration guide: `references/frontend-integration.md`
lstm-kirigaya