HumanKey

You authorize. AI executes.

Comment

Inspiration

AI agents are becoming capable enough to work for long stretches, but today the safest response to a consequential action is often either “stay at the terminal” or “give the agent broad standing authority.” HumanKey explores a better boundary: the agent keeps working, while a person retains the right to authorize the exact action that will occur.

What it does

Codex app-server approval events are normalized into a canonical HumanKey request. AgentGate owns request lifecycle and enforcement, preserves the exact action and verified context, and rejects stale, mutated, mismatched, expired, replayed, or ambiguous decisions. HumanKey presents that request to the operator and models a signed decision over the latest revision. Conversation is kept separate from authority: asking Codex a question cannot approve anything, and an authority-relevant change creates a new fingerprint and forces fresh review.

The submitted no-secret judge package demonstrates two question rounds, explanation without authority change, revision invalidation, reconnect without duplicate authority, one latest-revision approval, replay rejection, and denial. It runs locally from one checksum-verified command with an embedded inert fixture and no account, API key, GitHub token, Apple credential, source rebuild, or production network access.

The native SwiftUI companion provides the branded, privacy-aware request experience and tested device-owner-authentication, Secure Enclave/Keychain, pairing, pinned local request retrieval, signed mobile-decision, and generic notification-wakeup code paths. Build 21 passed the complete native suite, Release analysis, signed archive validation, and App Store Connect upload. During the final physical rehearsal, a pairing-repair/sequence-continuity defect made the end-to-end iPhone authorization route unreliable. We therefore do not claim a completed physical signed decision. The video's clearly labeled synthetic iPhone sequence illustrates the intended operator experience; the working, judge-testable functionality is the credential-free macOS package described above. Apple processing, TestFlight installation/smoke, remote APNs delivery, production Git execution, and reusable credentials are not submission claims.

How we built it

The majority of HumanKey was designed, implemented, adversarially tested, and documented with Codex using GPT-5.6 Sol in one canonical Build Week session. Codex accelerated protocol/schema design, failure-first security tests, TypeScript and Swift implementation, Codex app-server compatibility, SQLite lifecycle/replay persistence, TLS 1.3 boundaries, deterministic packaging, SBOM generation, native UX iteration, and submission evidence. Mahdi Hedhli made the product, scope, licensing, security/UX, distribution, and release decisions recorded in the repository collaboration log.

The stack includes TypeScript, Node.js, SQLite, strict I-JSON/RFC 8785 canonicalization, SHA-256, low-s ES256, TLS 1.3, SwiftUI, LocalAuthentication, Keychain/Secure Enclave APIs, XcodeGen, and Codex app-server. GitHub Spec Kit provided the MIT-licensed specification workflow. Three entrant-owned donor spikes were time-boxed as read-only references; no donor source, test, fixture, asset, or Git history was imported. The demonstrated HumanKey implementation is New Build Week work.

Challenges

The hardest problem was preserving a crisp distinction between helpful conversation and actual authority. We also had to bind every decision to the latest canonical request, make one-use consumption atomic, contain ambiguous outcomes, keep credentials and Apple signing metadata out of every agent-visible surface, and package a useful developer-tool demo without asking judges to rebuild or trust a production account.

Accomplishments

  • A working credential-free Codex-to-AgentGate judge package demonstrating exact one-use authority, revision invalidation, reconnect, replay rejection, and denial without production credentials.
  • Durable request, revision, replay, cursor, decision, grant, capability, lifecycle, and integrity-linked audit foundations.
  • A conversation-complete, branded judge experience that fails closed on stale decisions and replay.
  • A native SwiftUI companion with distinct production/evidence identities, privacy cover, accessibility coverage, device-owner authentication, Secure Enclave/Keychain paths, and generic notification wakeup registration, with the unresolved pairing-repair continuity defect disclosed rather than hidden behind the synthetic workflow visualization.
  • Repository verification, security checks, dependency policy, leakage checks, all 290 native tests, Release analysis, signed archive validation, and signed build-21 upload passed. Physical approval/execution, remote push, TestFlight processing/install, and smoke remain pending until separately verified.
  • A deterministic macOS arm64 package with an embedded runtime, SBOM, license inventory, zero leakage findings, two fresh local extraction rehearsals, and a byte-identical cross-parent build.

What we learned

Human approval is not a button; it is a protocol boundary. Operator comprehension, revision semantics, authenticated source identity, replay state, audit durability, and exact executor scope all have to agree. We also learned that a safe hackathon demo should make simulation obvious and production gaps visible instead of hiding them behind optimistic UX.

What is next

Next comes repairing and adversarially retesting pairing/sequence continuity before claiming the physical signed mobile-decision round trip, then a paired APNs provider route that carries only generic wakeups and a purpose-specific GitHub App or OAuth executor bound to exact remote/ref/commit state. Broader policies, cloud sync, Android, and generic secret retrieval stay behind those foundations.

Built With

Share this project:

Updates