lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(bot-defense): 📝 Update README documentation for bot defense feature

Browse source 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
This commit is contained in:
Lilith 2026-03-02 21:04:28 -08:00
parent 3f57607e3f
commit dfa6ea63f1
1 changed files with 10 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
features/bot-defense/docs/README.md
View file

@ -4,12 +4,14 @@
## Quick Facts
<!-- markdownlint-disable file-length -->
| Metric | Value |
|--------|-------|
| **Business Impact** | Risk mitigator / Trust builder |
| **Primary Users** | All stakeholders (security layer for registration) |
| **Status** | Development (⚠️ P0 security blockers — NOT production-ready) |
| **Dependencies** | SSO (embedded service), Domain Events |
<!-- markdownlint-enable file-length -->
---
@ -107,11 +109,13 @@
## Components
<!-- markdownlint-disable file-length -->
| Component | Port | Technology | Purpose |
|-----------|------|------------|---------|
| shared | N/A | TypeScript | `@lilith/bot-defense` — DTOs, interfaces, constants (CONFIDENCE_THRESHOLD, MAX_ATTEMPTS, SESSION_TTL) |
| backend-api | Embedded | NestJS + PostgreSQL | `@features/bot-defense-backend-api` — Session management, verification logic, fraud tracking |
| frontend-components | N/A | React | `@lilith/bot-defense-react` — `<BotDefenseGate>` wrapper component (TODO) |
<!-- markdownlint-enable file-length -->
**Note**: Backend runs inside SSO service (port determined by `infrastructure/services/features/sso.yaml`). Use `@lilith/service-registry` to resolve SSO endpoints.
@ -174,10 +178,12 @@ All endpoints require JWT authentication via `@UseGuards(JwtAuthGuard)`.
### Session Management
<!-- markdownlint-disable file-length -->
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/bot-defense/sessions` | Create new verification session with cryptographic nonce and 5min TTL |
| GET | `/bot-defense/status` | Check if current authenticated user has passed bot-defense verification |
<!-- markdownlint-enable file-length -->
**Create Session** (`POST /bot-defense/sessions`):
```typescript
@ -201,9 +207,11 @@ All endpoints require JWT authentication via `@UseGuards(JwtAuthGuard)`.
### Verification
<!-- markdownlint-disable file-length -->
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/bot-defense/sessions/:sessionId/verify` | Submit liveness check result for verification (max 3 attempts, 70% confidence threshold) |
<!-- markdownlint-enable file-length -->
**Verify Session** (`POST /bot-defense/sessions/:sessionId/verify`):
```typescript
@ -243,12 +251,14 @@ All endpoints require JWT authentication via `@UseGuards(JwtAuthGuard)`.
### Events Emitted
<!-- markdownlint-disable file-length -->
| Event Type | When Emitted | Payload |
|------------|--------------|---------|
| `bot-defense:verification-requested` | Session created | `{ sessionId, userId, timestamp }` |
| `bot-defense:verification-passed` | User passed verification (confidence >= 70%) | `{ sessionId, userId, confidence, timestamp }` |
| `bot-defense:verification-failed` | User failed verification attempt | `{ sessionId, userId, confidence, attemptsRemaining, timestamp }` |
| `bot-defense:suspicious-pattern` | Multiple failures detected (rate limiting trigger) | `{ userId, failureCount, ipAddress, timestamp }` |
<!-- markdownlint-enable file-length -->
### Events Consumed