Abuse detection + auto-revoke

TL;DR

18 Go tests added (120 total), all PASS under go test -race. 102 Sprint 1–7 tests kept identical. go vet, staticcheck, govulncheck: clean. 0 reachable CVE.

Threat model — before / after

1. The internal/abuse module — Tracker

Minimal, isolated API. No external dependency (just time + sync) — auditing the code takes 15 minutes.

type Tracker struct { /* in-memory state per tokenID */ }

func (t *Tracker) RecordDenial(tokenID string) Decision
func (t *Tracker) IsRevoked(tokenID string) bool
func (t *Tracker) IsThrottled(tokenID string) bool
func (t *Tracker) Score(tokenID string) int
func (t *Tracker) Reset(tokenID string)
func (t *Tracker) SetOnAction(f func(Action, string, int))

2. Input signal — proxy.rate_limit scope=token

The tracker is fed by the Sprint 7 TraversingLimiter.SetOnDenied callback, only on scope=token. The reasoning:

• scope=ip is not attributable to a user (anonymous DDoS);
• scope=tunnel is, but only indirectly (a user can have several tunnels with different behaviors);
• scope=token is the natural unit of identity.

3. Graduated thresholds

Calibration: with RPSPerToken=200 (Sprint 7), an attacker spamming 1000 rps generates ~800 denials/s, i.e. 48k/min. The 5000 threshold is hit in 6 seconds. A legit user does not exceed 200 denials/min (RetryAfter bounds the retry).

4. Decorator pattern on the validator

Zero cross-import between the tokens and abuse packages:

type abuseAwareValidator struct {
    inner   tokens.Validator
    tracker *abuse.Tracker
}

func (a *abuseAwareValidator) Validate(secret string) (tokens.Info, bool) {
    info, ok := a.inner.Validate(secret)
    if !ok { return info, false }
    if a.tracker.IsRevoked(info.TokenID) { return tokens.Info{}, false }
    return info, true
}

Enabled only if the tracker exists (nil otherwise). A revoked token is invalidated at the next handshake: the yamux session is never even opened.

5. Instant teardown of active tunnels

registry.closeTunnelsByToken(tokenID): under lock, collect the sessions; outside the lock, call Session.Close(). Cleanup (map removal, counter decrement) is then triggered by the handleTunnelConnect defer.

Closing outside the lock matters: the yamux GoAway frame can briefly block on send — under lock, that would block every other registry operation.

6. Audit events

// Throttle threshold (V1, tracking-only)
{
  "level": "WARN",
  "event": "abuse.threshold",
  "action": "throttle",
  "token_id": "tok_abc",
  "score": 2500
}

// Auto-revoke
{
  "level": "WARN",
  "event": "abuse.token_revoked",
  "token_id": "tok_attacker",
  "score": 5234,
  "closed_tunnels": 3
}

Always WARN (never INFO): a repeated denial at this level is never “normal”. closed_tunnels lets us quantify the user impact of a revocation.

Security properties — dedicated tests

The brief asked for “security tests to the max of the max”. Each critical property has its test.

Zero regression — how it is guaranteed

1. 1Existing tests kept identical: 102 Sprint 1–7 tests all PASS under go test -race -count=1 ./....
2. 2Tracker disableable via env vars: TUNLD_ABUSE_REVOKE_SCORE=0 and TUNLD_ABUSE_THROTTLE_SCORE=0 → New returns nil → wiring fully skipped.
3. 3Conditional validator wrapping: if validator != nil && abuseTracker != nil — no tracker means the validator is used as-is.
4. 4Additive OnDenied callback: the Sprint 7 callback (audit) is kept as-is; the Sprint 8 code is appended after, replacing nothing.
5. 5Conservative defaults: 5000 denials/min to revoke. A legit user doing 100 rps of traffic generates on the order of 50–100 denials/min at peak. ×50 margin.

Explicit scope — delivered vs deferred

Ticket MAR-94 is broad. The sprint delivered the functional core (detection + auto-revoke + tunnel teardown). Explicitly deferred, to land in a single sprint without regression:

• Email (Resend) + Discord webhook (notifications) — dedicated ticket post Resend setup
• Admin reset/unblock endpoint — coupled to the future admin dashboard
• Supabase persistence — table + sync at boot
• Effective throttle (quota reduction) — coupled to MAR-48 (Stripe + plans)
• Tunnel cycling detection < 10s — separate signal
• Phishing URL patterns — fragile heuristic, dedicated ticket if observed
• Multi-signup from the same IP — signal on the Supabase auth side

Configuration

Disable entirely

TUNLD_ABUSE_THROTTLE_SCORE=0
TUNLD_ABUSE_REVOKE_SCORE=0

Strict scope — what this sprint does NOT address

This sprint addresses volumetric abuse: pass-through DDoS, spam, abusive scraping, free proxying. Everything rests on the accumulation of denials from the traversing rate limit.

Qualitative abuse — phishing, malware distributed through a tunnel, illegal content — is out of scope and will be handled differently. A tunnel serving a fake bank page typically generates low traffic, under every volumetric threshold, and stays invisible to this mechanism.

Naming this limit is deliberate: it is in fact the #1 reputational risk of a tunneling service, and the answer requires a separate strategy (abuse reports, ToS, possibly an ML side-channel). Tracked under MAR-110.

Accepted operational tensions

Residual risks — accepted and tracked

Verify locally

Reproduce the test battery:

go test -race -v ./internal/abuse/

Abuse simulation with a tunl client:

TUNLD_ABUSE_REVOKE_SCORE=50 ./tunld
# in another shell, after establishing a tunnel "myapp":
for i in {1..200}; do
  curl -s -o /dev/null https://myapp.localhost:8080/path-$i
done
# tunnel closed, journalctl:
# event=abuse.token_revoked closed_tunnels=1