Code and session lifecycle
Beacon display ──(rotating entry code in QR)──> Phone opens /s/<code>
1. session-open POST only. Verifies the entry code (HMAC, time slot + grace), checks channel status,
rate limit (30/min per hashed IP), creates a scan session (short expiry). Nothing is consumed yet.
2. session-identity Channel's scanner identity: none | form (name/email) | account (magic link + passkey).
3. evidence Optional geolocation; PAL2: phone reads the challenge strip; PAL3: phone shows signed
response codes that the display camera observes (optical loop), optional encrypted photo.
4. session-commit PAL evaluator decides; commit_scan_v2 atomically consumes the code and appends a
hash-chained scan event. CHAINED channels then resolve the checkpoint (chain_advance).
5. pipeline For accepted scans only: channel actions run in order (redirect, presence, gate,
webhook, email, pinned script). A deny sets result_final; the original event is never changed.Repeat commits return the stored decision (idempotent). Scan events and the audit log are append-only and SHA-256 chained per organization; *Audit log → Verify chain* recomputes both chains on the server.
PAL levels and signals
| Level | Requirement | Signals recorded |
| PAL0 | Valid code only | code freshness |
| PAL1 | Fresh dynamic code plus supporting signals per policy | passkey, venue IP match, geolocation distance, device seen before |
| PAL2 | Phone camera reads the display's challenge strip within the calibrated latency (p99) | frames, server age, phone latency |
| PAL3 | Optical loop: display sees phone response codes; median/p95 loop time under threshold (p99 + 100 ms) | loops in window, median, p95, photo received |
Each level yields pass | flag | step_up | fail; the channel's PAL policy maps these to allow, allow-flagged (goes to the review queue), step-up or deny. Reasons and thresholds are stored with the session.
Rejection reasons
already_used · session_expired · channel_off · channel_locked · beacon_disabled · identity_failed · pal_fail · step_up_required · calibration_sample · not_found · rate_limited · review_rejected (compensating event after a reviewer rejects). Denials by actions or checkpoints appear as result_final = denied.
Calibration (PAL2 / PAL3)
- Beacons → *Calibration mode* on the display.
- Scan it at least 30 times from at least 2 different phones, standing where people normally scan.
- *Calibrate*: PAL2 stores median/p99 strip latency; PAL3 stores loop median/p95/p99 and sets the threshold to p99 + 100 ms (adjustable, audited).
- A PAL2/PAL3 channel can only be switched on when every active beacon is calibrated. Recalibrate after moving a display or changing lighting.
Verifying redirects
Redirect actions append qrc_scan, qrc_ts (unix seconds) and qrc_sig = hex(HMAC-SHA256(secret, "<qrc_scan>|<qrc_ts>")). The organization signing secret is shown once when created (Actions → *Verify visits on your site*); rotate it if lost.
// Node.js
import crypto from "node:crypto";
export function verifyQrc(query, secret, maxAgeSec = 300) {
const { qrc_scan, qrc_ts, qrc_sig } = query;
if (!qrc_scan || !qrc_ts || !qrc_sig) return false;
if (Math.abs(Date.now() / 1000 - Number(qrc_ts)) > maxAgeSec) return false;
const expected = crypto.createHmac("sha256", secret).update(`${qrc_scan}|${qrc_ts}`).digest("hex");
const a = Buffer.from(expected), b = Buffer.from(String(qrc_sig));
return a.length === b.length && crypto.timingSafeEqual(a, b);
}# Python
import hmac, hashlib, time
def verify_qrc(params: dict, secret: str, max_age: int = 300) -> bool:
scan, ts, sig = params.get("qrc_scan"), params.get("qrc_ts"), params.get("qrc_sig")
if not (scan and ts and sig) or abs(time.time() - int(ts)) > max_age:
return False
expected = hmac.new(secret.encode(), f"{scan}|{ts}".encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)Verifying webhooks
Each delivery is a JSON POST with x-qrc-signature = hex(HMAC-SHA256(endpoint_secret, raw_body)) and x-qrc-delivery (stable across retries — use it to de-duplicate). Verify against the raw body before parsing.
// Node.js (Express): app.post("/qrc", express.raw({ type: "application/json" }), handler)
import crypto from "node:crypto";
export function verifyWebhook(rawBody, signature, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected), b = Buffer.from(String(signature ?? ""));
return a.length === b.length && crypto.timingSafeEqual(a, b);
}# Python (Flask): verify_webhook(request.get_data(), request.headers.get("x-qrc-signature"), SECRET)
import hmac, hashlib
def verify_webhook(raw_body: bytes, signature: str | None, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")Evidence and retention
- Photos are encrypted on the display and stored in a private bucket; there are no public URLs or thumbnails and no automated face recognition.
- Viewing requires owner/admin and a written reason; the access is logged in the audit log before a 60-second link to the decrypted image is issued.
- A daily job deletes photos after the channel's photo retention period and removes raw fields (user agents, detailed session signals, beacon network details) after the organization's
retention_days. Counts and results are kept; every purge is logged.