humanymous Gate documentation

Navigation hub · Audience: everyone arriving for the first time.

Start here to find the right path for your role, then use the doc map to jump to any page in the set.

What is humanymous Gate?

humanymous Gate is a reverse-proxy enforcement layer that sits between your end users and your origin app. It terminates TLS, streams a detection bundle into the HTML, and scores each request across seven layers (L1–L7) — static client signals, fingerprint, client integrity, behavior, network/protocol, cross-check consistency, and scoring. The result is not a binary bot/human flag: each request gets a risk score from 0 to 100, which resolves to one of three verdicts — ALLOW, CHALLENGE (an accessible proof-of-work interstitial), or DENY — with hard rules able to promote a verdict on high-confidence evidence. Gate enforces that verdict at the edge and writes every decision to a tamper-evident audit log before it takes effect. It fronts your origin app and does not control it.

Note: This repository is a reference implementation, not a production-hardened build. See the “Reference implementation” note below.

Start here — pick your path

Five role-based landing pages, each a short orientation into the rest of the docs:

• Integrator — you are putting Gate in front of an app: topology, wiring, and rollout.
• Operator — you run Gate day to day: the Ledger, bans, policy, and on-call.
• Compliance / DPO — you own privacy and data handling: pseudonymization, retention, and right-to-erasure.
• Evaluator — you are assessing what Gate does and does not do before adopting it.
• Developer (Red/Blue) — you want to understand and extend the detection engine and its local test catalog.

New here? Which piece am I using? maps the three surfaces — the standalone detection engine (:8443), the Gate proxy (:8444/:8445), and the Detection Observatory — so you never confuse two binaries.

Doc map

The documentation set, grouped by Diátaxis quadrant.

Tutorial

• Quickstart — monitor mode (30 min) — stand up Gate in monitor mode and watch it score real traffic without enforcing anything.

How-to

• Deployment & policy operations — task recipes: TLS/certs, origin cloaking, admin listener + RBAC, moving a route from monitor to enforce, rate limits and bans.
• Configure attested routes (the attestation floor) — price the ALLOW on high-value routes: mark a route attested, its shared-key and cookie-jar preconditions, and how a real user clears the floor with a Pass or possession.
• Configure credential verifiers — wire WebAuthn, Privacy Pass, and Web Bot Auth so verifiable clients skip the friction and fast-path past the attestation floor.
• Ledger tour — a guided walk of the six console views (Overview, Integrity, Sessions, Rate Limits & Bans, Policy, Compliance).
• Verify the audit log — how to check the tamper-evident log without trusting the operator, and what each integrity-mismatch class means.
• Self-validation: red-team your own deployment — measure your own detection and false-positive rate with the bundled harness (defensive-only, local).
• Key management, rotation & recovery — the keystore, signing/HMAC/vault keys, ephemeral-vs-persistent identity, and recovery blast radius.
• Upgrade, migration & zero-downtime — the safe upgrade posture for a single node, and what multi-node rolling upgrades require.
• Cut a release — SemVer v* tags drive ghcr.io images and git-cliff release notes generated from Conventional Commits; the version-bump rules and the release flow.
• Observability & SIEM integration — the audit stream, integrity status, KPIs, and how to bridge to a SIEM.
• Watch detection happen live: the Detection Observatory — the local-only, dev-gated page that streams the L1→L7 pipeline as it scores a session.
• A guided tour of the Detection Observatory — an annotated screenshot walkthrough of the page before you run it.
• Integration troubleshooting & FAQ — symptom → cause → fix for the things that actually go wrong during integration.

Reference

• CLI, config & per-route policy — every flag, environment variable, policy preset, and the route match model.
• Hard rules, verdicts & signal IDs — the engine (HR-1..21) and Gate (HR-22..30) rule planes, verdict thresholds, and the lowercase l{n}.{group}.{item} signal namespace.
• Install, requirements & supported platforms — toolchain, build, ports, and dependencies.
• RBAC, separation-of-duties & dual-control — the role×capability matrix and which actions need a distinct committer.
• Data processing & personal-data inventory — what is observed vs stored, pseudonymization, retention tiers (RoPA-ready).
• Supported topologies (read before deploying) — which detection layers are active in each topology; the raw-TLS-termination requirement, the Core-vs-Gate split, and why a fronting CDN silently disables the network plane.
• Production-ready vs reference (prod-delta) — component-by-component status and the local↔production checklist.
• Security vulnerability disclosure policy — how to report a flaw in Gate itself, with a security.txt template.
• Deployment cost, latency & footprint — what adds per-request cost, the defined resource bounds, and how to measure your own numbers.
• Standards & regulatory mapping — control→requirement traceability (GDPR/PIPA/RFCs) and the audit-response evidence pack.
• On-call quick-reference & KPI thresholds — a one-screen cheat sheet: verdicts, top hard rules, the levers, and the ban ladder.
• Support, licensing & OSS notices — project-license status, third-party dependencies, and where to get help.
• Console localization & product-surface language — what is English today and what localization is a deployment responsibility.
• Documentation style guide — voice, terminology, and formatting rules for doc authors.

Explanation

• Concepts & glossary — how Gate sees a request — the L1–L7 pipeline and the vocabulary the rest of the docs use.
• What Gate is (and is not) — scope, the attacker-tier ceiling, and honest boundaries.
• Will this break my app? — safety, fail-open behavior, and a staged rollout from monitor to enforce.
• Where Gate fits — vs WAF / CDN bot manager / CAPTCHA, with the threat model and honest limitations.
• The control plane and the injected bundle — the /__hmn/ namespace, streaming injection, and avoiding CSP/routing collisions.
• DPIA companion & retention/lifecycle — a risks-and-mitigations input to your Data Protection Impact Assessment, and the retention model.

Runbook

• Incident runbooks (on-call) — step-by-step responses for the situations an operator meets in production.
• Kill switch & bans — blast radius, the ban ladder, apply/escalate/lift, and the dual-control gates.
• Right-to-erasure (crypto-shred) runbook — the DPO-gated, dual-control cryptographic erasure procedure.

End-user help

• Why am I seeing this? — plain-language help and appeal path for a blocked or challenged visitor.
• Challenge accessibility statement — the accessible-challenge commitment and what to do if the check is not usable.

Developer / advanced (Red/Blue)

The depth tier for developers who want to understand and extend the detection engine and its local test catalog. Start at Developer (Red/Blue).

• Which piece am I using? — the standalone engine (:8443) vs the Gate proxy (:8444/:8445) vs the Observatory, in one screen.
• Run the standalone detection engine — build and run bin/server.exe directly.
• Inside the detection engine — the Signal schema, the noisy-OR + LayerCap + dedup math, the hard-rule table, and the ScoreTrace.
• Extend the detector — add a signal, a cross-check, or a hard rule without regressing the low-false-positive principle.
• Inside the Detection Observatory — the live-telemetry transport and the complete, enumerated safety model.
• Red-team rules of engagement — the defensive, local-only, self-target-only boundary every Red page rests on.
• Red-team catalog reference — the profile contract, the 47-profile catalog, the raw-protocol attacks, and how a verdict becomes TP/FN/FP/TN.
• The Red catalog architecture — how the bundled profiles and the raw-protocol client are built.
• Write or extend a Red-team profile — author a profile and register it in all three places.
• How this reference implementation was built — the method behind the system: spec-first design, adversarial self-validation, and real-network validation.

Defensive-only

These docs describe protecting your own deployment. Any red-team, validation, or probing guidance targets a Gate instance you operate — never a third party’s systems.

Reference implementation, not production-hardened

This build is a reference implementation meant to show how the pieces fit together. Some capabilities are documented as reserved or as prod-delta (for example, ACME/bring-your-own certificates and a dedicated false-positive/appeal-queue view). Where a doc describes something the reference binary does not ship, it says so. Do not treat this build as production-ready without the production-hardening work called out in the relevant pages.