Docs

How QRChannels works, in detail.

The lifecycle of a scan, what each level checks, why scans are rejected, and how to verify our signatures in your systems.

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

LevelRequirementSignals recorded
PAL0Valid code onlycode freshness
PAL1Fresh dynamic code plus supporting signals per policypasskey, venue IP match, geolocation distance, device seen before
PAL2Phone camera reads the display's challenge strip within the calibrated latency (p99)frames, server age, phone latency
PAL3Optical 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)

  1. Beacons → *Calibration mode* on the display.
  2. Scan it at least 30 times from at least 2 different phones, standing where people normally scan.
  3. *Calibrate*: PAL2 stores median/p99 strip latency; PAL3 stores loop median/p95/p99 and sets the threshold to p99 + 100 ms (adjustable, audited).
  4. 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.