Build low-risk ESP32-C3 permission proof

[zoahdev]

Objective

Build a deliberately low-risk physical proof that a lightweight paper barrier moves only after a valid, single-use KGP capability and that every allow/deny result produces independently verifiable evidence.

Current status

The pre-hardware permission boundary and evidence contract are merged on main:

• boundary profile and host/device model;
• reviewed BOM, wiring, pin, and power constraints;
• strict serial transport contract;
• strict evidence Schema, explicit NOT_RUN template, and independent verifier;
• 74 repository tests passing on Python 3.11–3.13;
• CodeQL and package build passing.

Physical status remains NOT RUN. No GPIO, serial port, servo movement, physical PASS, functional-safety claim, or certification claim is being made. Procurement, assembly, filming, and physical execution remain founder actions.

Safety boundary

• Budget target: ¥100–170; hard cap ¥200.
• Allowed actuator: one SG90-class micro servo moving only a lightweight paper barrier.
• Default and failure state: locked/no movement.
• Do not connect door locks, vehicles, drones, alarms, industrial equipment, high-power motors, dangerous tools, access control, or third-party systems.
• The proof is not a functional-safety controller or safety certification.

Proposed hardware

• ESP32-C3 SuperMini
• SG90 micro servo
• SSD1306 OLED
• momentary button
• breadboard and jumper wires
• local decoupling capacitor and a suitable low-voltage supply

Purchase remains a founder action; no hardware should be ordered until the wiring and power plan are reviewed.

Trust boundary

1. Host evaluates policy and verifies/atomically consumes the KGP capability.
2. A device command is bound to the exact device, action, parameters, boot challenge, and monotonic counter.
3. The device persists replay state before actuating.
4. Any malformed message, bad authenticator, stale boot challenge, wrong counter, host disconnect, reboot, or serial corruption leaves the servo in the locked position.
5. The device returns a result that is bound into a signed KGP receipt on the host.

The repository must document that host compromise, firmware extraction, missing secure boot, and a demo pre-shared device key remain outside the proof.

Acceptance

• 20 no-grant attempts: 0 movements.
• 20 valid single-use grants: exactly 1 movement each.
• 20 replay attempts: all denied.
• Modified device, action, or parameters: denied.
• Wrong issuer: denied.
• Capability older than 10 seconds: denied.
• Concurrent attempts: exactly one winner.
• Replay after restart: denied.
• Host disconnect or corrupted serial input: locked/no movement.
• Allow and deny receipts verify independently.
• 100 continuous cycles without abnormal reset or overheating.

Deliverables

• reviewed wiring/power diagram and BOM;
• versioned serial protocol and threat model;
• ESP32-C3 firmware with fail-closed state machine;
• host bridge using the KGP gate and persistent replay store;
• hardware-in-the-loop runner that emits Schema-valid evidence;
• video shot list showing the grant, one action, replay denial, restart denial, and receipt verification without implying certification.

[zoahdev]

Draft PR #9 now implements the pre-hardware permission boundary and purchase gate:

• VerifiedCapability is required before issuing a device command;
• command signature binds device, capability, request digest, action, logical position, boot counter, live challenge, and sequence;
• the simulated device enforces exact 10-second expiry, one-winner concurrency, strict logical parameters, and persistent restart replay rejection;
• device acknowledgements are signed and checked against an explicit trust set;
• three strict Draft 2020-12 schemas are included;
• the hardware plan separates the 5 V servo rail from the board, keeps GPIO/OLED at 3.3 V, avoids known C3 strapping/USB/UART pins provisionally, and caps the planned cart at CNY 170;
• 48 repository tests and package build pass locally; GitHub Actions are running on the latest PR head.

This is still software-only. No ESP32-C3 firmware, serial transport, GPIO movement, physical acceptance evidence, or hardware-validation claim is included yet.

PR: #9

[zoahdev]

PR #9 has advanced beyond the initial boundary model:

• fixed a host-side one-shot gap where one VerifiedCapability could produce multiple fresh device commands;
• added a shared atomic issuance store, 64-way one-winner test, exact-expiry check, and SQLite restart persistence;
• added a strict physical-evidence Schema, explicit NOT_RUN template, and independent verifier;
• SIMULATION_PASS cannot validate as PHYSICAL_PASS;
• a physical pass requires exact acceptance counts plus byte-verified firmware, pinout, wiring photo, serial/host logs, video, receipts, and device acknowledgements;
• added an 8192-byte strict NDJSON serial framing model that remains locked on partial disconnect, duplicate keys, NaN/float, BOM, CRLF, invalid JSON, or overflow;
• repository suite is now 64 tests; current push and PR Actions are green on Python 3.11–3.13 and package build.

Latest head: 24cc035b6c76ac568f1cf321d9f139cf80cac170

PR: #9

Physical status remains NOT RUN. No GPIO, serial port, servo movement, or hardware evidence is being claimed.

[zoahdev]

Current pre-hardware status

Draft PR #9 is now stacked on the complete public reproduction surface and remains software/design evidence only.

• latest head: 2d7aa0acbf6f8e3aefd3389db9c8aeac8ba02b56
• local repository suite: 74 tests passed
• GitHub Actions: Python 3.11/3.12/3.13, package build, and commit-bound reproduction packet
• physical evidence status: NOT_RUN
• no GPIO, serial port, servo movement, physical PASS, functional-safety claim, or certification claim

The remaining founder-only step is still procurement and physical execution after the design PR is reviewed. The prohibited-device boundary remains unchanged.

[zoahdev]

Host-side hardware progress is now in Draft PR #14: #14

Implemented and verified:

• real lazy-loaded pyserial transport boundary
• one strict challenge → signed command → trusted acknowledgement exchange
• fail-closed timeout, truncation, surplus-frame, partial-write, malformed-challenge, and acknowledgement-binding behavior
• no-actuation HIL preflight capture
• physical-proof video/evidence checklist
• 79 local tests, wheel/sdist build, reproduction workflow, Python 3.11/3.12/3.13 CI, and CodeQL all pass

Evidence status remains NOT_RUN. Firmware, wiring, and physical acceptance runs are still pending; this comment does not claim physical validation.

[zoahdev]

Firmware and provisioning boundary merged

PR #15 is merged at commit �9b120f.

Completed software evidence:

• locked-by-default ESP-IDF 5.5.3 firmware for ESP32-C3;
• exact device/action/position, expiry, sequence, boot-counter, and live-challenge checks;
• trusted Ed25519 command verification and device-signed acknowledgements;
• replay and actuator state committed to NVS before the actuator call;
• secret-safe provisioning helper with a separate public record;
• strict host serial bridge and no-actuation HIL preflight;
• 82 repository tests on Python 3.11/3.12/3.13;
• CodeQL, package build, external reproduction, and official ESP-IDF cross-build all green;
• downloadable build artifacts from the merge workflow.

Physical evidence remains NOT_RUN. Still required from a real device: procurement, wiring and power inspection, firmware flashing/provisioning, the complete acceptance matrix, photos/logs/receipts/device acknowledgements, and the video record. No physical movement, safety certification, or production readiness is claimed.

[zoahdev]

A durable experimental firmware prerelease is now published: https://github.com/zoahdev/kinegrant-protocol/releases/tag/esp32c3-proof-v0.1.0

It is pinned to �9b120f57fbc0e525e66350d426decbbdbe1d94b and includes the application, bootloader, partition table, flashing arguments, and verified SHA-256 checksums. It is explicitly labeled unsigned, experimental, and NOT_RUN on physical hardware.

[zoahdev]

End-to-end acceptance checklist now available:
https://github.com/zoahdev/kinegrant-protocol/blob/main/proof/esp32-c3/ACCEPTANCE-CHECKLIST.md

It defines a phase-by-phase path (procurement → assembly → firmware → preflight → authorized run → evidence publication) with explicit pass criteria and a definition of done, referencing HARDWARE.md, TRANSPORT.md, hil_preflight.py, and the evidence schemas.

Budget note: complete new-purchase cart stays within CNY 100–170 (ceiling 200 incl. shipping) per HARDWARE.md. Any independent implementer with the hardware can follow the checklist and submit evidence; no safety certification or production claim is implied.