feat(visitor-analytics): add visitor identity, user-agent, and human/bot classification helpers #619

Context

Issue #618 adds the visitor analytics schema. Before request collection is wired into middleware, AWCMS-Mini needs small, testable helpers for visitor identity, path sanitization, user-agent parsing, and human/bot classification.

These helpers must be privacy-first and safe for offline/LAN operation.

Objective

Add reusable domain helpers for visitor keys, IP/user-agent hashing, user-agent parsing, route/path sanitization, referrer extraction, and human/bot classification.

Scope

Add helper modules under:

src/modules/visitor-analytics/domain/

Suggested files:

• visitor-key.ts
• user-agent.ts
• human-classifier.ts
• path-sanitizer.ts
• referrer.ts

Required capabilities:

• Generate or resolve an anonymous visitor key/cookie value.
• Hash anonymous visitor key.
• Hash IP address using a deployment salt.
• Hash user-agent where needed for deduplication.
• Parse browser name.
• Parse browser major version.
• Parse OS name.
• Detect device type: desktop, mobile, tablet, bot, unknown.
• Detect common bot/crawler user-agents.
• Sanitize paths and query strings.
• Remove sensitive query parameters.
• Extract referrer domain safely.
• Identify static assets and internal framework paths that should not count as pageviews.

Sensitive query parameters to remove at minimum:

• token
• code
• password
• secret
• email
• phone
• authorization
• access_token
• refresh_token
• reset_token
• mfaChallengeToken

Paths/patterns to skip at minimum:

• /_astro/*
• favicon
• images
• CSS
• JavaScript
• font files
• health endpoints
• OpenAPI/AsyncAPI/static spec files
• internal build/runtime assets

Out of scope

• Middleware collector.
• Database writes.
• API endpoints.
• Dashboard UI.
• External bot intelligence providers.
• Device fingerprinting beyond ordinary visitor cookie/hash and user-agent parsing.

Acceptance criteria

• Helpers are pure or close to pure where practical and are easy to unit test.
• Static assets and internal framework assets are excluded from pageview counting.
• Sensitive query parameters are removed before any path is stored.
• Bot/crawler user-agents are classified as bot.
• Unknown or ambiguous user-agents are classified as unknown, not blindly trusted.
• Authenticated admin/user sessions may be classified as human unless the user-agent is clearly bot.
• User-agent parser does not become an authorization or security decision point.
• Unit tests cover at least 20 common user-agent examples, including desktop, mobile, tablet, crawler, social preview bots, and unknown agents.
• No heavy dependency is introduced unless it is Bun-compatible and justified in docs.
• bun test passes.
• bun run check passes.

Security and privacy notes

• Do not implement aggressive fingerprinting.
• Do not store or parse request bodies.
• Do not store raw query strings containing tokens or secrets.
• Human/bot classification is for analytics only and must not be used as an authorization control.
• Prefer deterministic, minimal classification over invasive tracking.

Dependencies

Depends on #617 and should be implemented before request collection in middleware. Works best after #618 schema is available.