Platform · PIN Protocol
High-value handoffs that cannot be faked.
Cryptographic context binding ties every PIN to the driver\u2019s device, GPS coordinates, shipment ID, and a 5-minute time bucket. Screenshot the PIN, send it to a friend, and the system rejects the completion. Theft prevention built into the protocol, not bolted on after.
- 6-digit PIN generated server-side, hashed with SHA-256, plaintext never stored
- Bound to device fingerprint + GPS (±110m) + shipment + 5-minute time bucket
- Geofence enforcement: 0.5mi default tolerance, 2mi hard ceiling
- 15-minute auto-expiry — no stale PINs floating around
- Full audit trail: request, approve, view, complete, expire — all logged
01 · Why PINs
Auto theft is a real, ongoing problem in transport.
High-value vehicles get stolen at handoff in two ways: a fake driver presents fake credentials at pickup, or a real driver gets intercepted between pickup and delivery and the vehicle gets diverted. Most TMS platforms protect against the first scenario with a paper rate confirmation, which a competent thief can replicate in 10 minutes. Prevayl protects against both with cryptographic context binding that a paper printout cannot replicate.
- →Fake-driver attack: defeated by device fingerprint binding
- →Mid-trip diversion: defeated by GPS context binding
- →Phone-share attack: defeated by 5-minute time bucket binding
- →Replay attack: defeated by single-use PIN with auto-expiry
02 · The protocol
Three steps. Five guarantees.
Driver requests authorization at pickup geofence. Dispatcher approves and the server generates a 6-digit PIN bound to that exact context. Driver shows the PIN to the receiver, who enters it in the dealer or shipper portal. Server validates the PIN matches AND the context still matches AND the time bucket is current. Any mismatch — different device, different location, expired window, wrong shipment — the completion is rejected and an audit event is logged.
- →STEP 1: Driver requests at pickup geofence (lat/lng + device fingerprint)
- →STEP 2: Dispatcher approves; server generates PIN, hashes it, returns plaintext exactly once
- →STEP 3: Receiver enters PIN; server validates context binding before accepting
03 · Cryptographic context
What’s actually being hashed.
The pin_context_hash is a SHA-256 of (device_fingerprint, lat rounded to 3 decimals, lng rounded to 3 decimals, shipment_id, time_bucket). Lat/lng round to ~110 meter precision so honest GPS drift doesn’t reject a legitimate handoff, but a thief 5 miles away still fails. The 5-minute time bucket ensures the PIN cannot be reused even within the 15-minute expiry window — once the bucket rolls over, the hash no longer matches.
- →device_fingerprint: stable identifier from carrier app’s secure-store
- →lat / lng: rounded to 3 decimals (~110m precision tolerates GPS drift)
- →shipment_id: ties PIN to one specific load, not transferable
- →time_bucket: floor(now_ms / 300_000) — 5-minute granularity
- →SHA-256 hash stored in DB; plaintext PIN exists only in driver’s app for 15 min
04 · Geofence enforcement
Distance from target matters. A lot.
When a driver requests authorization, the server computes the Haversine distance from their reported GPS to the pickup or delivery address. Inside the 0.5mi (805m) default geofence, authorization proceeds normally. Between 0.5mi and 2mi, dispatcher must approve with an explicit override reason — which gets logged and tagged as either soft (under 1mi) or hard (over 1mi). Beyond 2mi (3220m), the request is rejected outright. The driver is not where they claim to be; the protocol does not negotiate.
- →GEOFENCE_DEFAULT_METERS = 805 (0.5 mi) — normal authorization
- →GEOFENCE_OVERRIDE_MAX_METERS = 3220 (2 mi) — dispatcher can override with reason
- →Beyond 2mi: hard reject, no override, "too_far_from_location" event logged
- →Override severity: soft (≤1mi) vs hard (>1mi) tagged for compliance review
05 · Audit trail
Every state transition. Permanent record.
shipment_events captures every PIN protocol event: handoff_requested, handoff_authorized (or handoff_geofence_override), handoff_denied, handoff_completed, handoff_expired, handoff_context_violation. The complete chain of custody is reconstructable from a single shipment ID, including who clicked what, where they were at the time, and what device they used. Insurance adjusters and law enforcement can request the audit pack and get a defensible answer in minutes.
- →Every state transition timestamped + actor-logged
- →Geofence override reasons captured verbatim
- →Context violations (device/location mismatch) flagged for review
- →Audit pack export: PDF + JSON for insurance + law enforcement
- →Retention: 7 years (matches DOT/IRS recordkeeping requirements)
EVERY CAPABILITY,
OUT OF THE BOX.
PIN expiry: 15 min
Auto-mark expired on completion attempt; no stale PINs in the field
No plaintext storage
SHA-256 hash only; plaintext PIN exists in driver app for 15 min
Concurrency-safe
Race-guarded UPDATE; two dispatchers approving simultaneously — one wins, one gets clean error
SMS fallback
10-min fallback channel if push notification delivery is delayed
READY TO MOVE?
Get started in under 10 minutes. Founding-50 customers lock 50% off — for life.