117 lines
3.5 KiB
Markdown
117 lines
3.5 KiB
Markdown
# OpenSpec Change: enterprise-gaming-api-plugin-anticheat
|
||
|
||
- **Change ID**: enterprise-gaming-api-plugin-anticheat
|
||
- **Package**: `@suaveplan/api-plugin-anticheat`
|
||
- **Category**: gaming/server
|
||
- **Target path**: `gaming/server/api-plugin-anticheat`
|
||
- **Status**: PROPOSED
|
||
- **Date**: 2026-04-24
|
||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-anticheat.md`
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Deliver `@suaveplan/api-plugin-anticheat` on the genesis branch from scratch at enterprise quality. The package provides server-side anti-cheat validation with speed, damage, action-rate, and teleport checks. A `ViolationTracker` records per-player violations with severity 1–10, decays accumulated violations over time, and computes a running trust score (starting at 100). When the trust score drops below the ban threshold, the tracker fires `anticheat:ban` event. HTTP routes expose reporting and admin endpoints. Genesis adds Zod violation schemas, structured errors, OTel violation counter, injectable clock, and 100% coverage.
|
||
|
||
---
|
||
|
||
## Current-state audit (genesis)
|
||
|
||
Package does not exist on genesis yet — fresh build.
|
||
|
||
---
|
||
|
||
## Available workspace deps on genesis
|
||
|
||
| Package | Role |
|
||
|---|---|
|
||
| `@suaveplan/error` (`workspace:^`) | `AntiCheatError`; `AC.*` codes |
|
||
| `@suaveplan/types` (`workspace:^`) | `Clock` |
|
||
| `@suaveplan/events` (`workspace:^`) | `anticheat:violation`, `anticheat:ban`, `anticheat:flag` events |
|
||
| `zod` (`catalog:forms`) | `Violation`, `CheckConfig` schemas |
|
||
| `@opentelemetry/api` (`catalog:observability`) | Violation counter, ban counter |
|
||
|
||
---
|
||
|
||
## Public API surface
|
||
|
||
```ts
|
||
type ViolationType = 'speed' | 'damage' | 'action_rate' | 'teleport' | 'custom'
|
||
|
||
interface Violation {
|
||
playerId: string
|
||
type: ViolationType
|
||
severity: number // 1–10
|
||
data?: unknown
|
||
timestamp: number
|
||
}
|
||
|
||
interface CheckConfig {
|
||
maxSpeed?: number // m/s
|
||
maxDamagePerSecond?: number
|
||
maxActionsPerSecond?: number
|
||
maxTeleportDistance?: number // meters
|
||
banThreshold?: number // trust score, default 30
|
||
decayRatePerSecond?: number // violation decay, default 0.1
|
||
}
|
||
|
||
function createViolationTracker(config: CheckConfig, options?: { clock?: Clock }): ViolationTracker
|
||
|
||
interface ViolationTracker {
|
||
check(playerId: string, type: ViolationType, value: number): void
|
||
addViolation(violation: Violation): void
|
||
getTrustScore(playerId: string): number
|
||
getViolations(playerId: string): Violation[]
|
||
isBanned(playerId: string): boolean
|
||
tick(dt: number): void // decay violations
|
||
reset(playerId: string): void
|
||
}
|
||
```
|
||
|
||
### HTTP Routes
|
||
|
||
| Method | Path | Description |
|
||
|---|---|---|
|
||
| `POST` | `/check` | Submit player action for validation |
|
||
| `GET` | `/players/:id/score` | Get trust score |
|
||
| `GET` | `/players/:id/violations` | List violations |
|
||
| `DELETE` | `/players/:id/violations` | Reset violations (admin) |
|
||
| `POST` | `/ban/:id` | Manual ban |
|
||
|
||
---
|
||
|
||
## File layout
|
||
|
||
```text
|
||
gaming/server/api-plugin-anticheat/
|
||
package.json
|
||
tsconfig.json
|
||
vitest.config.ts
|
||
src/
|
||
index.ts
|
||
error-codes.ts
|
||
types/common.ts
|
||
types/common.md
|
||
core/
|
||
violation-tracker/
|
||
violation-tracker.ts
|
||
violation-tracker.md
|
||
violation-tracker.types.ts
|
||
violation-tracker.test.ts
|
||
index.ts
|
||
routes/
|
||
anticheat.ts
|
||
anticheat.md
|
||
plugin.ts
|
||
plugin.md
|
||
tests/
|
||
integration.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## Impact
|
||
|
||
**Downstream**: `@suaveplan/api-plugin-game-server` hooks ban events to session kick. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.
|