Files

T

julian 35e593ab63 docs(wiki): DT-008 phantom-scan diagnosis + backfill bypass/relay-test concept pages

Two independent wiki updates bundled (all docs):

1. dingtian-dt008-reader.md: phantom optical decodes on the park-buzi EXIT
   reader (empty pre-opening site, low-sun afternoons). Chain of evidence:
   READ log lines carry the reader's own serial (H05MA5B0) → physical device,
   not a network source; snapshot shows nobody present; code shapes are the
   giveaway (6-digit numerics = checksum-less Interleaved 2-of-5, lone "C" =
   Code39/Codabar artifact) → 1D engine decoding sun-made stripe patterns
   (striped arm, fence shadows, glare). No fraud exposure (11-digit Luhn ids
   can't match); noise only. Fix on the entity page: vendor-tool symbology cut
   to QR+Code128 + min decode length, BOTH readers; config lives ON the device
   → re-apply after any factory reset/swap. Deliberately NOT filtering
   impossible codes server-side — probe recording is the anomaly path's job.

2. Backfilled two shipped-but-undocumented features (six code files already
   linked the first page as if it existed):
   - concepts/entry-presence-bypass.md — admin drops a FAULTY presence signal
     (granular radar/camera by decision, not a master switch); every flip is a
     signed config_change; persists till off; tickets stamped presenceBypassed;
     radar-bypass cooldown tradeoff; "the admin is not the adversary, but
     trusted never means invisible".
   - concepts/setup-relay-test.md — admin-only commissioning pulse, signed
     barrier_open_command BEFORE the fire so a test open never reads as the
     out-of-band-open fraud signal; saved controllers/declared relays only;
     radarAlert lamps excluded; pulseOpen only.
   Cross-linked from operator-issued-entry.md, cataloged in index.md, logged.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

2026-07-04 19:00:49 +02:00

4.0 KiB

Raw Permalink Blame History

type, tags, sources, updated, status

type

Entry presence-gate bypass (faulty radar / faulty camera)

The transient entry gates require a real vehicle before a ticket can mint: the radar/loop presence input and the camera vehicle-detection (entry-double-press for the physical button, operator-issued-entry for the booth button). When one of those devices is faulty — a dead radar, a camera that stopped pushing (g3h-anpr-push-gotchas) — the gate blocks legitimate transient entry until support fixes the hardware. This feature lets the admin drop a specific signal as a requirement until then. Built 2026-07-02 (migration 0020).

The principle: the admin is NOT the adversary

The threat-model adversary is the booth operator; the admin is the trusted party. So the admin may weaken an anti-fraud gate — but weakening it stays attributed and auditable (signed), because "trusted" never means "invisible" in this system. Compare operator-issued-entry, where the untrusted role gets capability + a red flag on every use; here the trusted role gets a switch + a signed record of flipping it.

Decisions (2026-07-02)

Granular, not a master switch. One flag per signal: a faulty camera drops only the camera check (radar still gates); a faulty radar drops only radar. Chosen over a single "bypass all" toggle so a single broken device never silently disables the other, still-working gate.
Persists until turned OFF, and every flip is signed. No auto-expiry (support visits are unpredictable); instead each enable/disable appends a config_change ledger event (setting: entryPresenceBypass.<signal>, value, prev, operator) — the append-only chain records who weakened the gate and when, and the OFF transition too. A no-op write (same value) signs nothing.

What a bypass changes

Physical button (EntryFlow.#suppressReason): camera bypassed → the camera press-gate is skipped; radar bypassed → the presence-loop check is skipped and the press falls through to the cooldown backstop. ⚠️ A dead loop can't re-arm one-car-one-ticket, so with radar bypassed and no entryCooldownSec configured there is no anti-double-press left — the admin's accepted tradeoff while bypassed (set a cooldown when bypassing radar).
Operator button (issueForOperator): the bypassed signal is dropped as a requirement; a refusal only happens when a still-required signal fails to confirm.
Auditability on every ticket: a ticket minted under a bypass carries presenceBypassed: ["radar"|"camera", ...] on its signed vehicle_entry (and refusal anomalies record it too) — so reconciliation can always tell which entries happened under a weakened gate.
Booth lights (booth-console): a bypassed signal renders as satisfied, so the operator's button-enable logic matches the server's.

As-built

Schema: site_config.bypass_presence_radar / bypass_presence_camera (booleans, default off = the normal both-required gate), migration 0020_entry_presence_bypass.sql. Read live per decision — a toggle needs no restart.
Endpoint: PUT /api/site-config/presence-bypass (routes/site.ts), admin-only (site:update), signs one config_change per actually-changed signal, 400 on non-boolean/empty.
UI: SetupWizard "presence gate" panel (two checkboxes + an amber "active" warning) after the controller section; config_change events render amber in the booth feed.
Tests: entry-presence-bypass.test.ts (gate decisions under each combination), presence-bypass-route.test.ts (RBAC, signing, no-op, validation), and entry-press-gate.test.ts (camera bypass on the physical press).
Fixing this surfaced a latent bug: firstRelayByDirection never attached presenceInput, so the operator-issue radar check had always read "presence loop unavailable" (fixed 2026-07-02).

4.0 KiB Raw Permalink Blame History