https://github.com/tokido-io/tokido-core
Production-grade MFA toolkit for Java. TOTP, recovery codes, extensible factors. GraalVM native-image ready.
https://github.com/tokido-io/tokido-core
authentication graalvm java mfa security totp two-factor
Last synced: 3 months ago
JSON representation
Production-grade MFA toolkit for Java. TOTP, recovery codes, extensible factors. GraalVM native-image ready.
- Host: GitHub
- URL: https://github.com/tokido-io/tokido-core
- Owner: tokido-io
- License: apache-2.0
- Created: 2026-04-18T05:55:59.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-28T05:22:32.000Z (3 months ago)
- Last Synced: 2026-04-28T05:25:43.548Z (3 months ago)
- Topics: authentication, graalvm, java, mfa, security, totp, two-factor
- Language: Java
- Size: 161 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# tokido-core
Production-grade MFA toolkit for Java. TOTP, recovery codes, extensible factors. GraalVM native-image ready.
[](https://github.com/tokido-io/tokido-core/actions/workflows/ci.yml)
[](https://codecov.io/gh/tokido-io/tokido-core)
[](https://github.com/tokido-io/tokido-core/actions/workflows/oidc-conformance.yml)
[](LICENSE)
## Why tokido-core?
- **Full enrollment lifecycle** — not just code verification, but enroll, confirm, verify, recover, and unenroll with audit events on every transition
- **Pluggable secret storage** — you choose how secrets are stored and encrypted (KMS, Vault, local keystore). The library never makes that decision for you.
- **GraalVM native-image ready** — no AWT, no runtime reflection. QR codes generated with pure `java.util.zip`.
- **Zero framework dependencies** — works with Quarkus, Spring Boot, Micronaut, or plain Java
- **Extensible factors** — TOTP and recovery codes ship in v1. Add WebAuthn, email OTP, or SMS by implementing `FactorProvider`.
## OIDC extension status (in development — alpha)
The OIDC extension is being built across six releases (M0 → M5). The current release is **`0.1.0-M0`** — scaffolding and conformance harness only; no engine code yet.
**OIDC basic conformance: 0/N** (M0 baseline — stub adapter returns `501 Not Implemented` for all endpoints; conformance pass-rate climbs as the engine implementation lands at M2 onward.)
| Module | Introduced | API status | Coverage | Notes |
|---|---|---|---|---|
| `tokido-core-identity-api` | M0 | empty skeleton | n/a | SPIs and protocol value types land at M1 |
| `tokido-core-identity-engine` | M0 | empty skeleton | n/a | Engine façade and handlers land at M1–M2 |
| `tokido-core-identity-jwt` | M2 (placeholder pom in M0) | not yet introduced | n/a | Nimbus-backed JWT signing; lands at M2 |
| `tokido-core-identity-broker` | M3 (placeholder pom in M0) | not yet introduced | n/a | OIDC RP federation; lands at M3 |
| `tokido-core-identity-mfa` | M4 (placeholder pom in M0) | not yet introduced | n/a | Bridge to existing MFA modules; lands at M4 |
> Coverage gates are intentionally suppressed in M0 (modules contain no Java sources yet); they re-engage at M1 when SPIs and protocol value types land.
The release cadence and milestone definitions are documented in [ADR-0004](docs/adr/0004-release-cadence.md). See `docs/adr/` for the full architectural decision record.
## Quick start
```xml
io.tokido
tokido-core-engine
1.0.0
io.tokido
tokido-core-totp
1.0.0
runtime
io.tokido
tokido-core-recovery
1.0.0
runtime
```
```java
// 1. Plug in your secret store
SecretStore store = new YourKmsSecretStore();
// 2. Build the MFA manager
MfaManager mfa = MfaManager.builder()
.secretStore(store)
.auditSink(event -> log.info("mfa: {}", event))
.factor(new TotpFactorProvider(TotpConfig.defaults().issuer("MyApp"), store))
.factor(new RecoveryCodeProvider(store))
.build();
// 3. Enroll a user
TotpEnrollmentResult totp = mfa.enroll(userId, "totp", EnrollmentContext.empty());
// totp.secretUri() → otpauth://totp/...
// totp.qrCodeBase64() → PNG QR code
// 4. Confirm enrollment (user proves they scanned the QR)
mfa.confirmEnrollment(userId, "totp", codeFromAuthenticatorApp);
// 5. Generate recovery codes
RecoveryEnrollmentResult recovery = mfa.enroll(userId, "recovery", EnrollmentContext.empty());
// recovery.codes() → ["04819237", "91847203", ...] — show once
// 6. Verify
VerificationResult result = mfa.verify(userId, "totp", codeFromUser);
if (!result.valid()) {
// Try recovery code
result = mfa.verify(userId, "recovery", recoveryCodeFromUser);
}
```
## Modules
| Module | Description | Dependencies |
|--------|-------------|--------------|
| `tokido-core-api` | SPIs and value types | none |
| `tokido-core-engine` | `MfaManager` — enrollment lifecycle coordinator | `tokido-core-api` |
| `tokido-core-totp` | TOTP factor with replay protection and QR generation | `tokido-core-api`, ZXing core |
| `tokido-core-recovery` | Recovery codes with bcrypt hashing | `tokido-core-api`, jBCrypt |
| `tokido-core-test` | `InMemorySecretStore` and `CollectingAuditSink` for testing | `tokido-core-api` |
## Security model
tokido-core **never stores or encrypts secrets**. You must provide a `SecretStore` implementation that handles encryption and persistence. This is a deliberate design choice:
- The library can't accidentally leak plaintext secrets
- You choose the encryption strategy (KMS envelope, Vault transit, local PKCS#12)
- You choose the storage backend (database, S3, file system)
- You own the key management lifecycle
For testing, use `InMemorySecretStore` from `tokido-core-test`.
## Building
```bash
git clone https://github.com/tokido-io/tokido-core.git
cd tokido-core
mvn verify
```
Requires Java 21+.
## Coverage
Line coverage is measured with [JaCoCo](https://www.jacoco.org/jacoco/) during `mvn verify` (minimum **90%** per module bundle). HTML reports are written under each module, for example `tokido-core-engine/target/site/jacoco/index.html`.
CI publishes reports to [Codecov](https://codecov.io/gh/tokido-io/tokido-core) (interactive tree and history). The badge above tracks default-branch coverage; PRs get a diff once the repository is connected to Codecov.
## Used in production by
[Tokido](https://tokido.io) — MFA-as-a-Service platform
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
Apache 2.0 — see [LICENSE](LICENSE).