CLI, config & per-route policy reference

Diátaxis quadrant: Reference. Audience: integrators and operators running humanymous Gate.

This page lists every command-line flag, environment variable, policy preset, route-table default, threshold, and ingress limit in the reference build of humanymous Gate (“Gate” after first mention). It is descriptive and complete, not a walkthrough — for a guided first run see the Quickstart (monitor mode); for rollout and safety reasoning see Will this break my app?.

Note: This repository is a reference implementation, not a production-hardened build. Values below are the reference defaults. Several production-shaped features do ship in the binary (for example -acme-domain / -tls-cert edge TLS, -admin-mtls-ca, Prometheus GET /__hmn/admin/metrics, and /__hmn/healthz + /__hmn/readyz); prod-delta is the remaining operational surface (SIEM shipping, external IdP/SSO, multi-node shared state beyond the optional Redis path).

Gate is the reverse-proxy enforcement layer. It terminates TLS, streams the detection bundle into HTML, scores layers L1–L7 inline, enforces the verdict at the edge, and writes every decision to a tamper-evident audit log. It fronts the operator’s origin app and does not control it.

CLI flags

Flags are defined in cmd/gate/main.go. The binary is built to bin/gate.exe from ./cmd/gate (module github.com/modootoday/humanymous).

Constraint-resolution features — all OFF by default, experimental. Read the trust caveat before enabling.

Environment variables

Startup log lines

Expect these lines on boot (values reflect defaults):

humanymous Gate dev on https://localhost:8444 -> http://127.0.0.1:9000 (monitor=false, tls=self-signed)
humanymous Gate admin console on https://localhost:8445/__hmn/admin/console
  dev tokens — auditor:<hex> operator:<hex> approver:<hex> dpo:<hex>

With -keystore set, one of these also appears:

keystore: created new sealed node identity at <path>

keystore: resumed persisted node identity from <path>

The dev tokens line prints only when tokens are generated (that is, when HMN_ADMIN_TOKENS is unset). When you supply HMN_ADMIN_TOKENS, use the values you provided.

Policy presets

Presets are defined in internal/gate/config.go. Five presets are implemented. Each sets whether the detection bundle is injected, whether the verdict is enforced, and (for strict and attested) fail-closed and synchronous-rescore behavior; attested adds the attestation floor.

Important: The low and api preset names are reserved and not implemented in the reference build. presetByName falls back to balanced for them. Do not rely on low or api as working presets.

The attestation floor prices the ALLOW; it does not detect. A coherent engine-level spoof cannot be told from a human past the T4 ceiling. On an attested route the floor makes the free ALLOW cost either possession or a per-session human Pass solve. It never blocks a human categorically — the demotion is always to a Pass challenge, never a DENY, so an unattested human solves the same Pass an anonymous visitor already solves.

Default route table

The default route table is set in main.go. Routes match by longest-prefix wins; anything unmatched uses balanced.

Note: -monitor or the kill switch downgrades enforce to monitor everywhere (GlobalMonitor), regardless of a route’s preset. See below.

A request resolves route to preset to verdict to edge action along this path:

flowchart TD
  A["request path"] --> B["longest-prefix route match"]
  B -->|"/login, /checkout, /admin"| P1["preset strict"]
  B -->|"/health"| P0["preset off"]
  B -->|"unmatched"| P2["preset balanced"]
  P0 --> BYP["no inject, no enforce (full bypass)"]
  P1 --> GM{"global monitor on? (-monitor or kill switch)"}
  P2 --> GM
  GM -->|"yes"| MON["inject, score and log, no enforce"]
  GM -->|"no"| SC["score L1–L7 to risk 0–100"]
  SC --> HR{"hard rule fired?"}
  HR -->|"yes"| DN["DENY to block"]
  HR -->|"no"| VB{"risk band"}
  VB -->|"0–29"| AL["ALLOW to pass"]
  VB -->|"30–69"| CHV["CHALLENGE to challenge_pow"]
  VB -->|"70–100"| DN

Monitor disambiguation

Three distinct things share the word “monitor”:

• The -monitor flag — a boot-global switch. It downgrades enforcement to monitor across every route for the life of the process.
• The monitor preset — a per-route setting. It injects the bundle and scores/logs that route, but enforces nothing on that route only.
• Monitor mode — the resulting runtime state of a route: score and log, enforce nothing. A route reaches monitor mode either because it uses the monitor preset, or because the global -monitor flag or the kill switch demoted it.

The kill switch is a fleet-wide dual-control flip that demotes hard-rule enforcement to monitor across all nodes (detection stops, traffic flows). Manual bans still enforce under the kill switch.

Warning: The kill switch is fleet-wide. Flipping it stops verdict enforcement on every node at once. It is a dual-control action (see Admin API).

Presets × global monitor mode

This table shows the effective runtime behavior of each preset with global monitor off (normal) versus on (-monitor flag or kill switch active).

Attestation-floor surface (ceiling-guard)

These apply only to attested routes. For a task-oriented walkthrough see Configure attested routes.

The step-up receipt carries a ±120 s clock-skew leeway; multi-host attested deployments should still run NTP.

Risk score and verdicts

The engine produces one of three verdicts — ALLOW, CHALLENGE, DENY — from a risk score of 0–100 (one decimal). Policy 1.0.0 thresholds are defined in internal/scoring/policy.go.

Edge verdict values are allow / challenge / deny / none (none = Unknown, no evidence yet). Edge actions (internal/gate/enforce.go): DENY → block (origin never contacted), CHALLENGE → challenge_pow (an accessible proof-of-work (PoW) interstitial from the control plane; origin never contacted), ALLOW → pass.

• Hard rules can promote or override the score-based verdict. See the Hard Rules, Verdicts & Signal-ID Reference.
• PoW upgrade: a score-based CHALLENGE with no hard rule fired becomes ALLOW if the session solved the proof-of-work (signal l7.pow.solved). PoW never overrides a hard rule — it proves CPU work, not humanity.
• Fail-open vs fail-closed on an Unknown verdict: fail closed (→ challenge) when the route is strict (fail-closed or sync-score) or the HTTP method is unsafe (POST/PUT/PATCH/DELETE). Fail open (→ pass) only for a safe-method (GET/HEAD) request on a non-strict route. The safe-GET fail-open on balanced routes is a documented accepted residual, covered meanwhile by fingerprint/subnet rate metering.
• A fingerprint-bound verdict trust token, when present and valid, lets ALLOW take a fast path with no re-scoring.
• Every enforcement decision is emitted to the audit sink before it takes effect.

Rate limiting and bans

The control-plane per-IP flood limiter guards /collect and /session. Defaults are tunable via Config.RateWindow / Config.RateSoft / Config.RateHard.

Auto-ban escalation ladder (with strike decay):

Ban keys are ip:<addr> or fp:<fingerprint>, with Source=auto or Source=manual. Bulk ban is temporary-only; permanent and CIDR bans are rejected from bulk and require dual-control.

Right-to-erasure hold

Right-to-erasure is cryptographic erasure (crypto-shred): it destroys the per-subject linkage key. A cancellable hold window precedes commit.

Warning: Cryptographic erasure is irreversible. Once the hold window elapses and the shred runs, the per-subject linkage key is destroyed and re-identification of those records is no longer possible. The audit chain and Merkle anchors stay intact and verifiable. See the Right-to-Erasure (crypto-shred) Runbook.

Ingress hardening

These limits apply to both the edge listener and the admin listener.

The dev certificate is self-signed in memory (ECDSA P-256), CN humanymous.local, SAN localhost, humanymous.local, 127.0.0.1, ::1. Browsers show a certificate warning in dev — this is expected. Production TLS is in the reference binary: set -tls-cert/-tls-key for bring-your-own PEM, or -acme-domain (and related flags) for Let’s Encrypt TLS-ALPN-01.

Control-plane endpoints (public edge)

The client-facing control plane is served on the public edge listener under the prefix /__hmn/ (Config.ControlPath = "/__hmn/"). The injected detection bundle loads via the control plane, and the browser beacons signals to /__hmn/collect on the same TLS connection the server uses to capture L5 (TLS/HTTP2) signals.

Note: /__hmn/admin/* is not served on the public edge — the public edge 404s it. The admin surface lives only on the admin listener.

Admin API (admin listener)

Served on the admin listener (-admin-addr, default 127.0.0.1:8445 — loopback; bind off-host only behind mTLS/SSO). The Ledger SPA is at https://localhost:8445/__hmn/admin/console and derives its API base as /__hmn/admin. Authentication is bearer (Authorization: Bearer <token>) with constant-time compare. A missing or invalid token returns 404 (deny-by-default, non-discoverable). Every authenticated access is meta-audited (admin.access) before serving.

Actor identity is server-derived from the token; request-body actor fields are ignored. RBAC roles: Auditor (read-only), Operator, Approver, DPO. In dev the console is injected with the Operator token so it can read and request; approvals need a distinct Approver token.

GET endpoints (read — Auditor and above)

POST endpoints (write)

Note: Dual-control means a distinct second identity commits the action: an Approver for permanent/CIDR bans and the kill switch, and a distinct DPO for erasure. The requester cannot approve their own action.

Request & response shapes

The authoritative admin request/response bodies. JSON field decoding is case-insensitive, so {"key": …} and {"Key": …} are equivalent; the canonical field names are shown below. Ban keys are always ip:<addr>, fp:<hash>, or cidr:<addr/mask>.

POST /bans — request {"Key":"ip:203.0.113.7","Reason":"scraper","Incident":"<opt>","DurationSec":3600}. A positive DurationSec on a non-broad key applies directly → {"ok":true,"permanent":false}. DurationSec:0 (permanent) or a cidr: key returns a pending dual-control action → {"pending":true,"approvalId":"<id>","needsRole":"approver"}.

POST /bans/bulk — request {"Keys":["ip:…","fp:…"],"Reason":"…","DurationSec":3600}. DurationSec must be > 0 (permanent bulk is rejected 400). Response {"ok":true,"applied":<n>,"skipped":<n>} (invalid/cidr: keys are skipped).

POST /bans/lift — uses a query parameter, not a body: POST /__hmn/admin/bans/lift?key=<ban-key>. Response {"ok":true,"lifted":<bool>}.

POST /erasure — request {"Subject":"<console pseudonym>","LegalBasis":"GDPR Art.17"}. Both fields required (400 otherwise). Returns a pending action → {"pending":true,"approvalId":"<id>","needsRole":"dpo"}.

POST /killswitch — request {"On":true}. Returns {"pending":true,"approvalId":"<id>","needsRole":"approver"}.

POST /approvals/{id} — no body; a distinct committer commits the pending action. Response varies by kind: ban {"ok":true,"committed":"ban","permanent":<bool>}; erasure {"ok":true,"committed":"erasure","scheduled":true,"shredId":"<id>","executeAtUnix":<unix>}; kill switch {"ok":true,"committed":"killswitch","monitorOn":<bool>}.

POST /erasures/{id}/cancel — no body. Response {"ok":true,"cancelled":"<id>"}.

GET /audit — response {"records":[<record>…],"count":<n>,"nextBefore":<seq>}, newest-first. Page with ?before=<nextBefore>; limit defaults to 50, max 500. Each record’s canonical fields: event_id, seq, node_id, ts (RFC3339 nanoseconds, UTC), event_type, event_version, actor{kind,id_pseudonym}, tenant_id, session_pseudonym, host, route_class (html|api|upgrade|control|static), verdict (allow|challenge|deny|none), risk_score, triggered_rules (["HR-…"]), top_signals[{id,verdict,conf}], enforcement_action, enforcement_mode (monitor|shadow|enforce), fail_mode (none|fail_open|fail_closed|degraded), fail_reason, latency_us, upstream{status,error_class}, tls{ja4_pseudonym,h2fp_pseudonym,sni_pseudonym}, config_version, key_id, data_class, the chain fields prev_hash/record_hash/hmac, and incident (the opaque handle, added at read time only). The ?host= filter is a case-insensitive substring; ?route= matches route_class exactly; ?rule= matches an HR-… in triggered_rules; ?subject= scopes to a single pseudonymous subject, matched against session_pseudonym or actor.id_pseudonym (GDPR Art. 15 subject access — pass the pseudonym, not a raw identifier).

GET /integrity — response {"node":"…","ok":<bool>,"class":"<mismatch-class>","records":<n>,"checkpoints":<n>,"witnessed":<bool>,"lastSTH":{"treeSize":<n>,"root":"<hex>"}}. On failure it adds divergentSeq, detail, and (if the witness attestation fails) witnessFailAt. The Signed Tree Head root and tree size are exposed; the raw Ed25519 signature and the witness public key are not returned by this endpoint in the reference.

GET /policy — response {"globalMonitor":<bool>,"killSwitch":<bool>,"effectiveMonitor":<bool>,"configVersion":"<signed hash>","routes":[{"prefix","preset","enforce","failClosed","syncScore","inject"}],"rateLimit":{"windowSec","soft","hard"},"retentionDays":<n>}. The signed effective-policy identity is the configVersion field.

GET /bans → {"bans":[{"key","reason","source","incident","strike","permanent","expiresInSec"}],"count"}. GET /erasures → {"scheduled":[{"id","legalBasis","requester","approver","executesInSec"}],"count"}. GET /approvals → {"pending":[{"id","kind","params","needsRole"}],"count"}. GET /whoami → {"id","role"}. GET /incidents/{handle} → the audit record (or 404; a per-operator lookup cap returns 429).

For hard-rule identifiers (HR-*), signal-ID namespaces, and per-verdict detail, see the Hard Rules, Verdicts & Signal-ID Reference. For how a request flows through L1–L7, see How Gate sees a request.

End-to-end run example

The following boots Gate with deterministic dev admin tokens, a public edge on :8444, the loopback admin listener on 127.0.0.1:8445, and an origin on http://127.0.0.1:9000. Run it from the module root after building bin/gate.exe. HMN_ALLOW_DEV_TOKENS=1 is required here because Gate fails closed on short/placeholder admin secrets — never set it in production, where you provide real high-entropy tokens.

HMN_ALLOW_DEV_TOKENS=1 HMN_ADMIN_TOKENS="auditor:aud-dev,operator:op-dev,approver:apr-dev,dpo:dpo-dev" bin/gate.exe -addr :8444 -admin-addr 127.0.0.1:8445 -upstream http://127.0.0.1:9000 -node gate-1

Expected startup output:

humanymous Gate dev on https://localhost:8444 -> http://127.0.0.1:9000 (monitor=false, tls=self-signed)
humanymous Gate admin console on https://localhost:8445/__hmn/admin/console

Because HMN_ADMIN_TOKENS is supplied, no dev tokens line is printed — authenticate the admin API with the tokens you provided:

curl -sk -H "Authorization: Bearer op-dev" https://localhost:8445/__hmn/admin/whoami

Tip: curl -k accepts the self-signed dev certificate. In production, use a trusted certificate and drop -k.

For a guided monitor-mode rollout and next steps, continue at Start here: Operator.