# 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`.