Skip to content
lgalabruPublic

About

Passport based attestations using zero knowledge proofs on Solana. iOS + CLI (requires Flipper Zero).

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

28 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Passport

Status: experimental OpenID4VP Groth16 via xark License: MIT

Passport turns the chip in your passport into private, verifiable claims. Hold an ePassport or ID card to an iPhone or a Flipper Zero. Passport reads the NFC chip and checks the issuing state's signatures. When a website, an app or an agent asks a question such as "is this person 18 or older?", it answers with a zero-knowledge proof of that one fact. The name, photo and document number stay on the device.

Proofs are Groth16 over BN254, with circuits written in Rust using xark. Anyone can check one off-chain, and a Solana program can check one on-chain and record it in the Solana Attestation Service, where other programs can condition on it.

Warning

Experimental research code. Do not use it for anything real. Nothing here has been audited. The proving keys come from xark setup --deterministic-rng, and there is no shared registry yet: each phone keeps its own, so a proof today only shows that the claims hold for a document enrolled on that phone, not that a state issued it. Request-object signatures are not checked. Formats, circuits and APIs will change without notice.

๐Ÿงญ Where this is going

Area What it is Status
๐Ÿ“– Read ICAO 9303 over NFC: BAC, secure messaging, DG1, DG2, EF.SOD, Active Authentication. One no_std reader runs on the iPhone and the Flipper. Works
๐Ÿ” Verify Passive Authentication (data group hashes, SOD signature, DSC chain to a CSCA) and Active Authentication, natively. Works: crates/pki
๐Ÿงฎ Claim passport_claim: age, nationality, issuer, expiry and birth date over the MRZ, plus registry membership. Proves in about 0.2 s on an iPhone. Verifiers pin the issuer, the claims, fresh iat and trusted roots. Works, with dev keys
๐Ÿ“ฒ Present The iOS app answers OpenID4VP requests with a compact, JWT-shaped claim proof. Works
๐Ÿชช Enroll passport_enroll: proves the SOD, the DSC chain, the DG15 binding and AA in zero knowledge, so the registry only admits documents a state issued. 664k constraints, about 1.4 s and 1.3 GB on a Mac. Works, with dev keys
โ›“๏ธ Attest The registry program (trusted DSC roots, enrollment proofs, one enrollment per chip, the commitment tree), and a verifier program that issues SAS attestations. The registry runs in surfpool; SAS is next
๐Ÿ•ฏ๏ธ Setup passport-ceremony: a multi-party Groth16 setup on the Perpetual Powers of Tau, with verifiable contributions. The tool works; the ceremony is to run
๐Ÿค– Agents passport CLI and MCP server with prove, verify and attest. setup and scan today

The design, and why it splits enrollment (heavy, once per document) from claims (light, every time), is in docs/design.md; what a verified proof means and what it still rests on is in docs/security.md. docs/protocol.md maps Tempo's passport-signer proposal to Solana, and docs/primer.md covers the zero-knowledge background.

๐Ÿš€ Quick start

The fastest way to see it work is the iOS app on a simulator, which reads a built-in software chip holding the ICAO specimen passport. You need Xcode with the iOS 27.1 SDK and the xark toolchain (see Circuits).

rustup target add aarch64-apple-ios aarch64-apple-ios-sim
just claim-artifacts                            # build the claim circuit and its dev keys
just ios-run                                    # build and launch on the iPhone Duo simulator
just relying-party 'age.gte(18)' nationality    # print a request link, then verify the answer
xcrun simctl openurl booted '<the link>'

In the app, add the sample passport, open the link, look at what would be shared, and approve. The relying party prints the claims it verified.

๐Ÿ“ฒ Clients

The holder app. A website or app sends an OpenID4VP request (an openid4vp:// link or QR code) asking for claims such as "18 or older". Passport shows exactly what would be shared. After Face ID, it proves the claims on the phone and posts the compact claim proof (docs/design.md ยง3) to the request's response_uri (direct_post).

To add a passport, the camera reads the MRZ, then CoreNFC runs the emrtd reader through crates/ffi. Simulators have no NFC, so they offer "Use Sample Passport" instead. On a phone, open clients/ios/Passport.xcodeproj and set your team. The circuit, minimized R1CS and proving key add 3.3 MB to the app.

The same tap reads EF.SOD and DG15 and runs Active Authentication, and the app lists whether the passport can enroll, check by check (RSA-2048 signers and RSA-1024 chip keys for now). "Verify Passport" then downloads the enrollment circuit, proves on the phone and sends the proof to the registry through a Kora relayer; claim proofs from then on are checked against the on-chain registry. Point a build at a registry, RPC endpoint, relayer, artifact host and signer list with the PassportRegistry keys in clients/ios/Config/Info.plist.

On iPhone Duo the app follows the hinge. Folded, the cover display shows a single stack. Unfolded, the document sits on one half and the request or detail on the other, split at GeometryProxy.reservedRegions(kind: .division).

Flipper Zero: clients/flipper

A Flipper app that reads a passport or ID card over NFC (BAC, DG1, DG2 and the advanced data groups) with the same reader. It targets firmware API 87 (Flipper firmware 1.3 to 1.4).

rustup target add thumbv7em-none-eabihf
cargo install flipperzero-tools      # for `storage`
just flipper-install                 # build and copy to /ext/apps/NFC/passport.fap
passport scan                        # print what the Flipper reads

The MRZ key you enter is saved to /ext/apps_data/passport/mrz_info.txt, and data groups such as DG2 are written next to it. src/{session,screens,flow}.rs hold everything that can be tested on a laptop; src/device/ is the thin firmware glue.

CLI and MCP: crates/cli

just install passport
passport setup

passport setup writes ~/.config/passport/config.yaml, installs the passport agent skill at user level through skills.sh, and registers passport mcp with Claude Code and Codex. --no-skill and --no-mcp skip a step (a new config records the choice), --force rewrites an existing config, and PASSPORT_CONFIG points somewhere else.

passport mcp serves over stdio. Its one tool today, setup, does what passport setup does and returns a JSON report of each step.

๐Ÿ—‚๏ธ Repository layout

passport/
โ”œโ”€โ”€ clients/
โ”‚   โ”œโ”€โ”€ ios/                  ๐Ÿ“ฒ the holder app (SwiftUI, links the Rust core)
โ”‚   โ””โ”€โ”€ flipper/              ๐Ÿฌ Flipper Zero reader app
โ”œโ”€โ”€ crates/
โ”‚   โ”œโ”€โ”€ document/             driver vocabulary: Driver trait, claims, evidence (no_std)
โ”‚   โ”œโ”€โ”€ drivers/emrtd/        ICAO 9303 reader: BAC, secure messaging, LDS decoding (no_std)
โ”‚   โ”œโ”€โ”€ pki/                  Passive and Active Authentication, natively
โ”‚   โ”œโ”€โ”€ attest/               claim language, compact claim proofs, OpenID4VP
โ”‚   โ”œโ”€โ”€ ffi/                  C ABI for the iOS app: reader, specimen chip, attestation flow
โ”‚   โ”œโ”€โ”€ circuits/
โ”‚   โ”‚   โ”œโ”€โ”€ gadgets/          xark gadgets: SHA-1, RSA, PKCS#1 v1.5, ISO 9796-2, Poseidon, LDS
โ”‚   โ”‚   โ”œโ”€โ”€ claim/            passport_claim
โ”‚   โ”‚   โ”œโ”€โ”€ enroll/           passport_enroll
โ”‚   โ”‚   โ””โ”€โ”€ sha1, dsc-sig, aa, rsa2048/   building blocks of passport_enroll
โ”‚   โ”œโ”€โ”€ ceremony/             ๐Ÿ•ฏ๏ธ multi-party Groth16 setup (powers of tau, phase 2)
โ”‚   โ”œโ”€โ”€ programs/registry/    โ›“๏ธ the registry: enrollment proofs, nullifiers, commitment tree
โ”‚   โ”œโ”€โ”€ programs/aa-verifier/ โ›“๏ธ Solana program verifying a passport_aa proof (dev key)
โ”‚   โ”œโ”€โ”€ e2e/                  on an in-process surfpool: the AA verifier, enrollment and a claim
โ”‚   โ”œโ”€โ”€ integration/          the reader against a simulated chip
โ”‚   โ”œโ”€โ”€ types/, core/         config schema; config, setup and scan
โ”‚   โ””โ”€โ”€ cli/, mcp/            the passport binary and its MCP server
โ”œโ”€โ”€ skills/passport/          ๐Ÿง  the agent skill `passport setup` installs
โ””โ”€โ”€ docs/                     ๐Ÿ“ design, protocol mapping, primer

Each document format is a driver under crates/drivers/ implementing passport_document::Driver. A driver says what it can do (Read, and SignChallenge for chips that sign) and returns a DocumentRecord: shared Claims plus the issuer-signed Evidence a verifier or prover needs. emrtd is the only driver so far. ISO 18013-5 mobile driving licences, EUDI Wallet credentials and national eID smart cards are candidates.

๐Ÿ› ๏ธ Hack on it

Prerequisites

  • Rust (stable, 1.88 or later) and just.
  • For circuits: the xark toolchain below.
  • For the iOS app: Xcode with the iOS 27.1 SDK.
  • For on-chain tests: cargo-build-sbf.

Everyday loop

just ci          # fmt, clippy -D warnings, tests, no_std and Flipper builds
just coverage    # line coverage, needs cargo-llvm-cov; target is 80%

Circuits

Circuit crates compile and test through the xark CLI, pinned to the same version as the xark crates in Cargo.toml. It needs only stable Rust (1.89 or later) and the wasm32-unknown-unknown target, which it adds on first use:

cargo install --locked --git https://github.com/blueshift-gg/xark --tag v0.3.0 xark-cli

cargo test -p passport_aa (or any circuit crate) builds the circuit on demand and checks it against reference vectors. just circuits-build compiles every circuit and reports constraint counts.

On-chain verification

crates/programs/aa-verifier bakes in the verifying key xark exports for passport_aa and verifies proof || public_inputs through the alt_bn128 syscalls. crates/e2e builds it with cargo build-sbf, starts an offline surfpool inside the test process, deploys the program with the surfnet_writeProgram cheatcode, and sends a proof of the reference Active Authentication vector. The genuine proof lands; a tampered proof or a changed public input fails.

just aa-artifacts   # regenerate dev keys, proof and fixtures after a circuit change
just e2e

The keys come from xark setup --deterministic-rng 1 --domain radix2, so the fixtures are reproducible and must never be deployed anywhere real. The radix2 domain is what the passport prover's arkworks FFTs expect; xark's own prover also takes the smaller smooth domains it picks by default.

CI

ci.yml runs on every push to main and every pull request:

Job What it checks
rust cargo fmt, clippy -D warnings, workspace tests, and the no_std and Flipper builds. Crates whose tests build circuits are left to circuits.
circuits Installs xark at the pinned rev, builds passport_claim with dev keys, runs the circuit and claim-proof tests, and uploads the artifacts.
secrets gitleaks over the full history.

ios.yml runs by hand: it needs a macOS runner whose Xcode has the iOS 27.1 SDK.

License

MIT. See LICENSE.

About

Passport based attestations using zero knowledge proofs on Solana. iOS + CLI (requires Flipper Zero).

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Packages

Contributors

Languages