feat(entry): operator-issued entry + exit plate-swap reconciliation
Build desktop / desktop (push) Successful in 4m29s
Build & push images / images (push) Successful in 2m51s
CI / check (push) Successful in 37s

Two halves of one anti-fraud design.

(A) Operator-issued entry — when the physical entry button is broken, an
operator can issue an entry ticket so a real car isn't blocked out of the lot.
This hands the operator-adversary a mint, so it is:
  - PRESENCE-GATED like the physical button: a real car must be present (radar/
    loop AND camera busy). Enforced BOTH sides — the server re-checks current
    presence so a direct POST can't bypass a disabled button; no presence loop
    => feature unavailable; a no-presence attempt signs an anomaly.
  - FLAGGED: vehicle_entry source=manual + operatorInitiated + operator, PLUS a
    companion entry.operatorIssued anomaly (the adversary path always leaves a
    red-flag row).
  - capacity-OVERRIDE allowed but stamped lotFull (a broken button mustn't trap
    a legit car).
  New session:create permission (migration 0019 -> operator role, admin-
  revocable), POST /api/entry/issue (open-shift gated), EntryFlow.
  issueForOperator; the fraud-critical print->sign->open->snapshot sequence is
  factored into one shared #issueTicket (button + operator). UI: the entry
  BarrierLight becomes a clickable issue-control when presence+permission+shift
  meet (confirm -> issue).

(B) Exit plate-swap reconciliation — defends the ticket-swap fraud the mint
enables (paid car let out on a fresh $0 ticket, original ticket lingers
"inside", occupancy drifts up by phantom cars). The plate is the invariant:
ExitFlow.#reconcilePlateAtExit compares the exiting plate against all OPEN
sessions' entry plates, EXACT + HIGH-CONFIDENCE only (>=0.85; a fuzzy read never
gates — ANPR is advisory). On a match under a DIFFERENT ticket:
  - BOOTH path: returns swap_suspected + signs exit.plateSwapSuspected; the
    pay/exit modal shows a red warning + "Override & release" (override signs an
    attributed exit.plateSwapOverride). Flag+override, never a silent hard block
    (exit fails-open; a plate is never the sole gate).
  - READER path (no operator): log-only anomaly + fail-open.
  Extended BoothExitResult + /api/exit (override); boothExit client returns a
  structured swap result.

Verified: full monorepo build/lint/test green (229 server tests incl. 4 new:
hold-on-swap, override-releases-with-attribution, low-confidence-no-warning,
own-plate-no-warning). New wiki: operator-issued-entry.md +
plate-reconciliation.md; cross-linked from entry-exit-points, capacity-
occupancy, index. Preserves "a plate never OPENS a barrier alone — and now never
TRAPS a car alone either."

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
This commit is contained in:
2026-07-01 12:17:52 +02:00
parent 114a32e6f2
commit 33c4ea1e91
20 changed files with 760 additions and 62 deletions
+70
View File
@@ -0,0 +1,70 @@
---
type: concept
tags: [parking, booth, entry, threat-model, anpr, presence]
sources: []
updated: 2026-07-01
status: settled
---
# Operator-issued entry (broken entry button)
When the physical entry button is broken, an operator can **issue an entry ticket** from the booth so
a real car isn't blocked out of the lot. This hands the [[threat-model|operator (the adversary)]] a way
to mint entries — so it is **flagged, presence-gated, and paired with an exit defense**
([[plate-reconciliation]]). Built 2026-07-01. Companion to [[entry-exit-points]] (the entry flow it
reuses) and [[capacity-occupancy]].
## Why give the operator this at all
An operator *could* mint tickets to defraud — but a broken entry button otherwise **blocks the whole
lot**, which is worse and more common. So the feature exists, and the fraud it enables is defended
downstream (see the "ticket-swap" scenario in [[plate-reconciliation]]) rather than by withholding the
capability.
## The three controls that make it safe
### 1. PRESENCE-GATED — a real car must be there (radar AND camera)
The operator button obeys the **same rule as the physical button**: it is only active when **BOTH**
presence conditions meet —
- **radar/loop present** (a presence input is shorted at the entry barrier), AND
- **camera confirms** a vehicle in the zone (the entry lane is "busy").
This ties every mint to a **real vehicle physically at the entry** — the operator can't pad occupancy
with phantom tickets, and (crucially) it guarantees the entry snapshot captures a **plate**, which is
what [[plate-reconciliation]] reads at exit. **No presence loop configured → the feature is
unavailable** at that site (we require both; no weaker camera-only fallback).
**Enforced on BOTH sides.** The UI only enables the entry [[booth-console|BarrierLight]] as a clickable
issue-control when `radar.entry && lanes.entry` (both true) and the operator holds `session:create`.
The **server re-checks** current presence (`LaneStatus.snapshot().entry === true` AND the entry relay's
guard `present === true`) and **refuses** otherwise — so a direct `POST /api/entry/issue` by the
operator-adversary can't bypass a disabled button. A refused (no-presence) attempt signs an
`anomaly` (`entry.issue.noPresence`) so probing the endpoint is itself in the tamper-evident record.
### 2. FLAGGED — every operator mint leaves a red-flag row
The issued entry is a **real** `vehicle_entry` (so occupancy/tariff/exit all work), but:
- `source: "manual"` + `operatorInitiated: true` + `operator` on the signed payload, AND
- a **companion `anomaly`** (`entry.operatorIssued`) — mirroring the [[booth-exit-flow|barrier
re-open]]: the operator-adversary path always leaves an explicit anomaly for [[reconciliation]].
### 3. Capacity OVERRIDE is allowed but recorded
Unlike the physical button (which refuses transient entry when the lot is [[capacity-occupancy|full]]),
the operator **can** issue over capacity — a broken button mustn't trap a legit car when the count is
near/at the cap (and the count may itself be inflated by the very fraud this defends). But an over-cap
mint stamps `lotFull: true` + the occupancy on the events, so the override is visible.
## Wiring
- **Permission:** `session:create` (new; migration 0019 grants it to the default `operator` role;
admin-revocable per role, so an admin can turn off an operator's ability to mint). Admin has it in code.
- **Route:** `POST /api/entry/issue` — `session:create` + an **open shift** (a minted entry belongs to
an accountable operator, like the money path).
- **Server:** `EntryFlow.issueForOperator(operator, cameraBusy)`. The fraud-critical
print → sign(vehicle_entry) → pulseOpen → snapshot → cache sequence is a **single shared
`#issueTicket`** used by both the physical button and this path (no divergent copy).
- **UI:** the entry `BarrierLight` becomes clickable (confirm → issue) only when presence + permission +
shift are satisfied; the exit light stays a pure indicator.
## Relates
- [[plate-reconciliation]] — the exit-side defense against the ticket-swap this capability enables.
- [[entry-exit-points]] — the entry flow + snapshot/ANPR path reused here.
- [[capacity-occupancy]] — why occupancy integrity matters (the swap fraud drifts it upward).
- [[threat-model]] — the operator-adversary framing all three controls serve.