7-QES · On-device LiDAR Client Contract

LiDAR → 7-QES → TQPP

iPhone 14 Pro Max LiDAR captures the dimensional fingerprint. 7-QES pre-signs it through seven post-quantum layers. TQPP then triple-chain signs the 7-QES-bound fingerprint.

On-device Flow

Step 1 · Capture

LiDAR Scan

iPhone 14 Pro Max LiDAR sensor returns a 3D point cloud of the physical asset. Serialise to a stable byte array (Float32 x,y,z triples).

Step 2 · Fingerprint

SHA3-256 Hash

Compute dimensional_fingerprint = sha3(serialised_point_cloud). Use the iOS CryptoKit SHA3 hash implementation; never store the raw point cloud on-device.

Step 3 · Submit

POST /api/tqpp/scan/submit

iOS app POSTs the dimensional fingerprint + a lidar_payload block ({point_cloud_hash, dimension_summary, capture_device}). Server runs 7-QES, then TQPP.

Step 4 · Verify

7-Cert Response

Server returns nfcc.combined_hash (TQPP triple-signed), qes_certificate.combined_hash (7-QES 7-layer artefact), and 7 independently verifiable layer records.

PLATFORM REQUIREMENT · device.platform must be "ios" when a lidar_payload is supplied. Mismatches return 400 BAD_REQUEST.

POST /api/tqpp/scan/submit — Request Body

Field	Type	Required	Notes
`scanFingerprint`	string	yes	`0x`-prefixed SHA3-256 hex (66 chars). Used as the seed for the 7-QES prebind fold.
`commodityClass`	string	yes	UBVCF code, 4-digit pad: `UBVCF-FOOD-AGRI-0001` — matches `migrations/1743000000028_seed_universal_commodity_catalog.js`.
`device.platform`	enum	yes	`"ios"` required when `lidar_payload` is present. `"android"` allowed only without LiDAR payload.
`device.model`	string	no	e.g. `"iPhone 14 Pro Max"`.
`device.appVersion`	string	no	URTI mobile app version.
`lidar_payload`	object	conditional	Present only on iOS LiDAR scans. `{ point_cloud_hash, dimension_summary, capture_device }`. Triggers 7-QES prebind before TQPP.
`lidar_payload.point_cloud_hash`	string	conditional	0x-prefixed SHA3-256 of the serialised point cloud. Echo of the client-side hash step.
`lidar_payload.dimension_summary`	string	conditional	Human-readable dimensions, e.g. `"12.4x8.2x3.1 cm"`.
`lidar_payload.capture_device`	string	conditional	`"iPhone 14 Pro Max LiDAR"` or manufacturer string.
`dimensional_fingerprint`	string	conditional	`0x`-prefixed SHA3-256 of the point cloud. If supplied, fed to the 7-QES fold alongside the scan seed.
`provenance`	object	no	Optional jurisdiction/GPS provenance metadata (country, gpsLat, gpsLng, captureTimestamp).
`scanPayload`	object	no	Free-form scan stats (NOT the point cloud). The server injects `lidar_prebind` here when 7-QES prebinds.

Sample Request — iOS LiDAR submit

POST /api/tqpp/scan/submit · application/json

// iPhone 14 Pro Max LiDAR → 7-QES → TQPP — single roundtrip
{
  "scanFingerprint": "0xa1b2c3…",            // SHA3-256(client-side seed)
  "commodityClass":  "UBVCF-FOOD-AGRI-0001", // 4-digit pad
  "device": {
    "platform":    "ios",
    "model":       "iPhone 14 Pro Max",
    "appVersion":  "1.0.0"
  },
  "lidar_payload": {
    "point_cloud_hash":   "0x4e7b…",          // = dimensional_fingerprint
    "dimension_summary":  "12.4x8.2x3.1 cm",
    "capture_device":     "iPhone 14 Pro Max LiDAR"
  },
  "scanPayload": {
    "scan_session_id": "demo-session-001",
    "operator_id":     "op-42"
  }
}

Response — 200 OK

Server → client · both 7-QES and TQPP combined_hashes present

{
  "status":       "verified",
  "qes_prebound": true,
  "nfcc": {
    "nfcc_id":           "NFCC-XXXX-XXXX-XXXX",
    "combined_hash":     "0x…",             // TQPP: 3 PQC signatures + 7-QES fingerprint
    "signatures": {
      "dilithium": { "algorithm": "CRYSTALS-Dilithium-3" },
      "falcon":    { "algorithm": "FALCON-1024" },
      "xmss":      { "algorithm": "XMSS-QRL" }
    },
    "chain_anchors":     { "polygon_tx": …, "ethereum_tx": …, "qrl_tx": … }
  },
  "qes_certificate": {
    "combined_hash": "0x…",             // 7-QES: foldCombinedHash(L1..L7)
    "algorithms":    [ … 7 entries … ],
    "layer_count":   7
  }
}

Companion endpoints

Endpoint	Auth	Purpose
`GET /api/qes/status`	public	Stack composition + engine mode + the on-device `source_contract` block.
`POST /api/qes/certify`	`X-QDI-Key`	Standalone 7-QES certify path; accepts a `lidar_payload` envelope directly via the `payload` block.
`GET /api/qes/verify/:nfcc_id`	`X-QDI-Key`	Three-phase integrity check. Pass `?payload=<base64-json>` to re-run deterministic layers (1, 3, 5, 6, 7).
`GET /api/qes/layer/:nfcc_id/:layer_no`	`X-QDI-Key`	Single-layer read for independent audit (1–7).
`GET /api/tqpp/ubvcf`	public	Enumeration of all 217 UBVCF commodity classes so the iOS scanner UI does not need a bundled manifest.
`GET /api/tqpp/scan/:nfccId`	public	Re-fetch + re-verify an existing TQPP certificate.
`POST /api/tqpp/scan/:nfccId/verify`	public	Manual verify endpoint — supports a modified payload for tamper-detection.