Ezkey

Ezkey is an open-source cryptographic MFA platform built as a distinct alternative to browser-centric authentication models.

It does not implement FIDO2 or WebAuthn, and it should not be understood as a simplified passkey variant. Ezkey follows its own protocol and trust model, built around a direct cryptographic relationship between a trusted backend and a mobile application.

Ezkey is designed for developers, especially backend developers, who want a self-hosted MFA system with strong cryptographic guarantees, explicit trust boundaries, and APIs that stay practical to integrate.

It also includes an Admin UI for human administration, giving operators a direct surface for platform and tenant workflows without changing Ezkey's backend-first trust model.

Status

Ezkey is in public alpha. This repository is the product source; there are no published release packages yet (no GitHub Releases / installable binaries to consume). Technical identity of a live deploy is the git SHA — see docs/VERSIONING_AND_DEPLOY_TRACEABILITY.md. Pull-request and main feedback from GitHub Actions is described in docs/DEVELOPMENT.md § Continuous Integration (required-check candidate: ci-gate).

Try the live stack via the community path on ezkey.org — community instance and community guided tour (French under /fr/).

Mobile app: still in internal testing — not on app stores. For the community walkthrough, build and sideload the Android app from this monorepo in developer mode, or use the separate Ezkey Demo Device (simulated phone for demos only; not a store client).

What Exists Today

• Admin UI for day-to-day human administration across Global Admin and Tenant Admin workflows.
• Admin API for administration, onboarding, and authentication management.
• Auth API for mobile enrollment and authentication flows.
• Integration API for machine-to-machine auth attempt lifecycle operations.
• Mobile app for device enrollment and user approval flows.
• CLI and test tooling for local stack usage, validation, and fallback workflows.
• Self-hosted stack for local development, demonstrations, and integration work.

The Admin UI is the primary operator surface. Global Admins manage tenants, platform operations, and sensitive platform actions such as cryptographic key operations. Tenant Admins manage integrations, enrollments, API keys, and day-to-day tenant administration.

Security Design

Ezkey is built around cryptographic continuity across the full flow, not around a single isolated proof.

• During enrollment, bind and verify are cryptographically linked.
• During authentication, pending and respond are cryptographically linked.
• One-time proof tokens and signature validation protect the flow against replay and tampering.
• When secure private-key storage is available on the device, Ezkey uses it as an implementation building block, not as the foundation of its identity.
• In the current Android reference app, per-enrollment private keys live in Android Keystore with StrongBox requested when available, while long-lived application secrets such as enrollmentProofToken and integrationPublicKey are sealed separately at rest through an app-level Android Keystore AES key. These are related hardening layers, not a single "StrongBox unlocks all app secrets" model.

This is what makes Ezkey a distinct backend-to-mobile security model rather than a passkey-derived approach.

Quick Start

The supported local stack path is the Bash clean start from ezkey-tests:

./ezkey-tests/clean-start.sh

Default product runtime profile is integrity (audit-chain + heartbeat on). For an opt-in base stack (MFA crypto on; audit-integrity monitoring off — limited claims, not “eval-only lab”):

./ezkey-tests/clean-start.sh --runtime=base

See docker/README.md § Runtime profiles.

On Windows, use Bash as well, for example through Git Bash.

For stack details, modes, and test-oriented workflow:

• ezkey-tests/README.md
• docker/README.md
• docs/LOCAL_STACK_PORTS.md

Host Java reactor (fresh clone)

To compile and unit-test the Java modules on the host (Windows, macOS, or Linux), install JDK 25 and Maven 3.9+, then from the repository root:

./scripts/build.sh --diagnose-only
./scripts/build.sh

Use Git Bash on Windows. Do not start with a bare mvn checkstyle:check on an empty ~/.m2: Checkstyle depends on an unpublished in-repo module, and build.sh installs it first. Full notes: docs/DEVELOPMENT.md § First clone on a new workstation.

Documentation

• product-docs/global/product-intent.md — Product intent (canonical). Root PRD.md is a stub that points here.
• docs/PROJECT_POSITIONING.md - Strategic positioning and project philosophy.
• docs/README.md - Documentation index.
• docs/ECOSYSTEM_REPOSITORIES.md - Planned integration repos (SMS, directory sync shells) beside the core monorepo.
• docs/ADMIN_UI.md - Admin UI purpose, operator roles, capabilities, and documentation boundaries.
• docs/ENDPOINT.md - API reference (section-scoped; not a cold-start dump).
• docs/CRYPTO.md - Device vs integration signing algorithms.
• docs/RECOVERY_CODES_LIFECYCLE_ANALYSIS.md - Recovery-code lifecycle analysis and recommended regeneration model.
• docs/DEVELOPMENT.md - Development workflow.
• docs/OPERATIONAL.md - Operational and deployment guidance.
• - Public static site () and Cloudflare workflow notes.

Security and Compliance

Ezkey is developed with strong cryptographic validation and self-hosted operational control in mind. The project also aims to move in a direction that is favorable to operator-visible operational discipline, without claiming certification or standards equivalence. See product-docs/global/normative-posture.md.

License

This project is licensed under the MIT License. See LICENSE for details.