Superapp / Product requirements / shield

Harbor Rates · Edge shield — product requirements

Version 7.29 features33 requirements16 Must Open appJSONMarkdown

Harbor Rates is a container freight rates and booking portal that sits behind Edge shield, an edge bot-management layer. An open zone (overview and edge trace) needs no check; the rates board is a managed zone fronted by a checkbox interstitial with up to 3 attempts; the booking desk is a strict zone with a single attempt. Every verdict gets an Incident ID and is listed in a per-tab edge trace, and blocked visitors can file a false-positive report.

Problem. Shippers need live rates and booking space, while the operator must keep automated scraping and abuse away from them. Visitors must be able to understand why they were challenged or blocked, and a wrongly blocked human must have a way to report it with a reference that support can look up.

Users

Goals

Out of scope

Contents

Overview

Open landing page that explains the three protection zones.

FR-OVR-01
Must
The overview loads without any check and presents the three zones with a coloured tag and status dot each.
  • Hero "Ocean freight rates, refreshed weekly" with tiles Lanes 16, Carriers 5 and Edge PoP (a three-letter code)
  • Rates board: amber MANAGED tag, "Challenge on entry"; Booking desk: red STRICT tag, "Challenge on entry"; Edge trace: grey OPEN tag, "Open"
  • A green "Protected" chip in the top bar with tooltip "Traffic to this site passes through Edge shield"
FR-OVR-02
Should
A protection-levels legend states what each level means.
  • OPEN: "No check."
  • MANAGED: up to 3 attempts, then blocked
  • STRICT: "One attempt; any automation signal blocks the visitor."
  • The Edge PoP tile tooltip reads "Point of presence that served this tab"
FR-OVR-03
Should
Zone cards reflect the tab’s current state.
  • A blocked zone shows a red dot and "Blocked" while the other zone is unaffected
  • A cleared zone shows a green dot with "Cleared · m:ss"

Managed challenge (rates board)

Checkbox interstitial in front of the rates board with up to 3 attempts.

FR-CHL-01
Should
Opening the rates board without clearance shows a full-page interstitial with all its parts.
  • Tab title "Just a moment… · harbor-rates.example"
  • Heading with the host name, "Verify you are human by completing the action below.", a checkbox widget labelled "Verify you are human" with the Edge shield mark and "Privacy · Terms" links
  • Chip "Attempt 1 of 3" with tooltip "Failed attempts block this browser for the rates board"
  • Footer with an Incident ID (16 hex characters, a dash and the PoP code), "Protected by Edge shield" and a MANAGED tag
FR-CHL-02
Must
A failed managed check advances the attempt counter and re-issues the challenge.
  • Widget shows a red ✕ "Failed" and "✕ Verification failed. Try again."
  • A new Incident ID is shown, the widget resets after about 2 s and the chip reads "Attempt 2 of 3", then "Attempt 3 of 3"
FR-CHL-03
Must
The third failed managed check blocks the visitor for the rates board.
  • The widget shows "Blocked", then the block page appears with tab title "Attention Required! · harbor-rates.example"
  • The explanation states the browser failed the verification challenge three times in a row
  • The block is per zone: the booking desk is not affected
FR-CHL-04
Could
An unused challenge expires after 60 seconds and can be refreshed without costing an attempt.
  • Widget turns orange with label "Expired · Refresh"
  • After "Refresh" the widget is back to "Verify you are human" and the chip still shows "Attempt 1 of 3"

Strict zone (booking desk)

Single-attempt interstitial in front of the booking desk.

FR-STR-01
Must
A visitor showing automation signals is blocked on the first attempt and never sees the booking form.
  • Interstitial subtitle "Verifying your connection", a "Single attempt" chip and the line "This area is under strict protection — one attempt only."
  • After the click the widget shows "Blocked" and the block page "Access to this page is denied" appears with a STRICT tag
  • The page explains that a security service protects the site from automated access
  • No Lane select, stepper or "Request booking" button is shown
FR-STR-02
Must
A block persists for the tab: reloading shows the same block page and Incident ID without a new challenge.
  • No checkbox widget is shown after reload and the Incident ID is unchanged
  • The overview shows the Booking desk as blocked while the Rates board still shows "Challenge on entry"

Block page and false-positive report

What a blocked visitor sees and how they can appeal.

FR-BLK-01
Must
The block page always shows the Incident ID of the block, with a copy control, so a report can be filed.
  • Headline "Access to this page is denied" / "You are unable to access harbor-rates.example"
  • Footer shows the Incident ID as 16 hex characters, a dash and the PoP code, plus a copy icon (toast "Copied")
  • "Your IP: Click to reveal" reveals the address
FR-BLK-02
Could
The block page diagram marks the edge as the failing hop.
  • You / Browser: green ✓ "Working"; Edge shield / Security layer: red ✕ "Blocked"; host: green ✓ "Working"
  • Nodes are joined by dashed grey connectors
FR-BLK-03
Must
A blocked visitor can file a false-positive report; the resulting ticket cites the Incident ID of the block shown on the page.
  • "Report a false positive" opens a modal showing the block’s Incident ID under the title
  • On success: "Report received", a ticket "FP-" followed by six digits and the same Incident ID
  • The note "The site owner reviews reports within two business days." is shown
  • The Details box shows a live counter such as "22 / 500"
FR-BLK-04
Should
The report form validates its fields and reports each problem separately.
  • Invalid email: "Enter a valid email address"
  • No reason chosen: "Choose a reason"
  • Reason "Something else" with fewer than 10 characters of details: "Describe the problem (at least 10 characters)"
  • Nothing is filed until every rule passes
FR-BLK-05
Could
The report modal can be dismissed by ✕, Cancel or a click on the backdrop; nothing is filed and the form is empty when reopened.

Edge trace

Per-tab, open-to-all log of every edge decision with its reasoning.

FR-TRC-01
Should
A fresh tab shows an empty trace and clean zone tiles.
  • MANAGED "Rates board" tile: "Not cleared", "Failed attempts: 0 / 3"; STRICT "Booking desk" tile: "Not cleared"
  • Table row "No edge decisions yet — open the Rates board or Booking desk."
  • Legend chips "strong · 60", "medium · 25", "weak · 10" and a PoP chip equal to the overview tile
FR-TRC-02
Must
Every verdict is recorded with the same Incident ID that the visitor saw, the zone, path, verdict, bot score and signals.
  • Serving an interstitial adds a blue CHALLENGE row (score "—", "challenge served") whose Incident ID equals the interstitial footer
  • A failed managed check adds an amber RETRY row; a block adds a red BLOCK row; a pass adds a green PASS row
  • BLOCK and RETRY rows always show the numeric score and at least one signal chip (strong signals have a red dot, tooltip "strong signal")
  • The score bar tooltip reads "Bot score <n> · <zone> threshold <t>" with thresholds 50 (managed) and 25 (strict)
FR-TRC-03
Should
Zone tiles summarise the managed and strict state.
  • Managed tile counts failed attempts, e.g. "Failed attempts: 1 / 3"
  • A blocked zone shows a red dot with "Blocked (attempts)" for managed and "Blocked (signals)" for strict
  • Three failed managed checks yield two RETRY rows and one BLOCK row
FR-TRC-04
Could
The Incident ID in the trace has a copy icon (tooltip "Copy", toast "Copied").

Detection and scoring

How client signals and request headers become a verdict.

FR-SCR-01
Must
The score is the sum of the hit signals (strong 60, medium 25, weak 10, capped at 100); a visitor passes only when the score is below the zone threshold (managed 50, strict 25).
  • Strong signals: automation flag, headless user agent, automation runtime, invalid proof-of-work
  • Medium: no pointer movement, instant click, missing Accept-Language; weak: empty plugin list, empty language list, zero-size window
  • A visitor with the automation flag set is never passed in either zone
FR-SCR-02
Must
A successful check issues a clearance for that zone only, valid for 15 minutes, and resets that zone’s failed attempts.
  • The rates board shows a green "Cleared · 14:5x" chip counting down, tooltip "Edge clearance for the rates board; you will be checked again when it runs out"
  • Clearing the managed zone does not clear the strict zone and vice versa
  • While clearance is valid the zone opens without a new interstitial

Rates board

Filterable, sortable board of 16 container lanes (managed zone).

FR-RAT-01
Must
After clearing the managed check the rates board opens and lists all lanes with a clearance countdown and summary tiles.
  • Header "Rates board", "Week 42 · published Mon 12 Oct 2026"; lane count "16 of 16 lanes"
  • KPI tiles "Cheapest 40HC $2,650 · KRPUS→USLAX", "Avg transit 21 days", "This week ▲ 6 ▼ 6 = 4"
  • The trace gains a green PASS row for MANAGED /rates
FR-RAT-02
Should
Filters for origin, equipment, direct-only and search combine, and the lane count updates.
  • Origin "VNSGN · Ho Chi Minh City" gives 5 lanes; with 40HC 3 lanes (R-1001, R-1002, R-1004); with Direct only 2 lanes (R-1002 is transshipment)
  • Origin VNSGN with equipment "All" and Direct only gives 4 lanes (R-1001, R-1003, R-1004, R-1016)
  • Search "kestrel" within that set gives 1 lane (R-1004)
FR-RAT-03
Should
Sortable headers sort ascending then descending with a visible direction marker.
  • Default All-in ascending (▲), first row R-1016 $560; clicking All-in gives ▼ with R-1012 $6,450 first
  • Reliab. ascending starts at R-1010 (66%, red dot); Transit ascending starts at R-1016 "3 d"
  • Other sortable headers show a faint ↕
FR-RAT-04
Must
A lane’s all-in price equals base plus all surcharges, and the drawer breakdown sums to it.
  • R-1007 drawer: "Shanghai → Rotterdam", Base $3,015, BAF $480, CAF $55, THC $210, "All-in per container $3,760"
  • Meta row shows carrier "Orion Lines", chip "40HC" and "28 days direct"
  • Trend shows low $2,800 and high $3,015
FR-RAT-05
Could
Row markers read correctly.
  • R-1005: VNHPH tooltip "Haiphong", carrier MRD tooltip "Meridian Box", Transit "34 d" with a "T/S" badge (tooltip "Transshipment via a hub port")
  • Reliab. "68%" with a red dot; Δ wk green "▼ 4.2%"; falling sparkline; surcharge badges BAF, PSS, THC, EBS (tooltip "EBS · Emergency bunker surcharge · $120")
  • All-in "$5,490" and Valid "10-31" with an amber "!" badge
FR-RAT-06
Could
The star icon pins a lane without opening the drawer, and the "★ Pinned" switch filters to pinned lanes.
  • Tooltip "Pin lane"; the star fills yellow
  • Pinned filter shows "1 of 16 lanes"; unpinning the only lane shows "0 of 16 lanes" and "No lanes match these filters."

Booking desk

Request container space once cleared by the strict check.

FR-BKG-01
Must
A cleared visitor can request a booking; the estimate is quantity times the lane all-in price and the request is listed with its reference.
  • Lane "KRPUS → USLAX · HLX · 40GP · $2,450" with quantity 1 shows "$2,450 (1 × $2,450)"; with 3 containers "$7,350 (3 × $2,450)"
  • The − button is disabled at quantity 1
  • Confirmation "Booking requested", "Reference HBR-xxxxx · total $7,350"
  • "Your requests" lists HBR-xxxxx · R-1015 · 3 · 2026-11-20 · — · Lotus Garments Co. with an amber "Requested" status
FR-BKG-02
Must
The booking desk validates lane, quantity, shipper, ready date, UN number and equipment, and creates nothing on failure.
  • No lane: "Choose a lane" (lane select outlined red)
  • Ready date after the lane validity: "Rate is valid until 2026-10-31" for R-1016
  • Quantity must be 1–50: "Containers must be 1–50"; shipper required: "Shipper is required"
  • Dangerous goods require "UN" followed by four digits: "UN number must look like UN1263"
  • Dangerous goods on reefer equipment (40RF): "Reefer equipment cannot carry dangerous goods"
  • A valid dangerous-goods booking shows an orange UN badge on its row
FR-BKG-03
Should
Booking a lane from the rates drawer opens the strict check and preselects the lane after clearing.
  • R-1001 preselects "VNSGN → USLAX · ORN · 40HC · $3,715"
  • The rates board stays open without a new interstitial

API protection

Protected API routes honour the same clearance as the pages.

FR-API-01
Must
Protected API routes never return data without clearance.
  • The rates and booking routes answer 403 with marker "challenge", the zone and an Incident ID
  • A challenge request for a zone returns an id, nonce, difficulty 14 bits, attempt 1 and maxAttempts (3 managed, 1 strict)
  • A failed strict verification answers 403 "Access to this page is denied" with marker "block" and an Incident ID; later requests return the same block and Incident ID
  • The trace lists that BLOCK with its signals (e.g. webdriver and pow_invalid)

Non-functional requirements

NFR-01
Must
The Incident ID format is 16 lowercase hex characters, a dash and the PoP code, and an Incident ID is unique per verdict.
NFR-02
Should
State (clearance, blocks, trace, reports) is isolated per browser tab; a fresh tab starts with no clearance and an empty trace.
NFR-03
Should
Challenge and clearance behaviour is deterministic: repeated visits within clearance never loop back to the interstitial.

Glossary and rules

Incident IDReference for one edge decision: 16 hex characters, a dash and the PoP code.
PoPPoint of presence: the edge location that served the tab, shown as a three-letter code.
ClearanceA 15-minute permission, per zone, issued after a passed check.
Bot scoreSum of signal weights (0–100) compared with the zone threshold.