{"id":37024698,"url":"https://github.com/ivanstambuk/openauth-sim","last_synced_at":"2026-01-14T02:59:36.820Z","repository":{"id":316962737,"uuid":"1065484949","full_name":"ivanstambuk/openauth-sim","owner":"ivanstambuk","description":"Authentication protocol simulator in Java 17 covering OATH HOTP/TOTP/OCRA, FIDO2/WebAuthn, EMV/CAP, and EUDI wallet/OpenID4VP","archived":false,"fork":false,"pushed_at":"2025-12-13T22:16:15.000Z","size":12687,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T08:57:26.684Z","etag":null,"topics":["authentication","cap","cryptography","emv","eudi-wallet","fido2","java","oath","ocra","otp","simulator","webauthn"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivanstambuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-27T20:29:51.000Z","updated_at":"2025-12-13T22:16:19.000Z","dependencies_parsed_at":"2025-09-27T22:20:51.893Z","dependency_job_id":"1dd6c17e-c65d-454d-b826-8557e0ee7de2","html_url":"https://github.com/ivanstambuk/openauth-sim","commit_stats":null,"previous_names":["ivanstambuk/openauth-sim"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ivanstambuk/openauth-sim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanstambuk%2Fopenauth-sim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanstambuk%2Fopenauth-sim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanstambuk%2Fopenauth-sim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanstambuk%2Fopenauth-sim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivanstambuk","download_url":"https://codeload.github.com/ivanstambuk/openauth-sim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanstambuk%2Fopenauth-sim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","cap","cryptography","emv","eudi-wallet","fido2","java","oath","ocra","otp","simulator","webauthn"],"created_at":"2026-01-14T02:59:36.009Z","updated_at":"2026-01-14T02:59:36.804Z","avatar_url":"https://github.com/ivanstambuk.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAuth Simulator\n\nOpenAuth Simulator is a Java\u0026nbsp;17, Gradle-based environment for emulating contemporary authentication credentials and protocols (HOTP/TOTP, OATH OCRA, EMV/CAP, FIDO2/WebAuthn, and EUDIW OpenID4VP wallet artefacts). The project is intentionally greenfield and AI-native; we optimise for fast iteration by AI agents, incremental steps, and the ability to evolve APIs as requirements change. The simulator can be consumed via five surfaces: a Native Java API, CLI commands, REST API endpoints, an operator console web UI, and an MCP agent facade.\n\n![Operator console walkthrough showing HOTP/TOTP/FIDO2 panels](docs/_assets/app-demo.gif)\n\n## What is this?\n\nThis is an AI-native, spec-driven codebase: production feature code is generated by AI agents from specifications and runbooks, with humans acting as reviewers and owners rather than hand-writing implementation.\n\n- Simulates OATH HOTP/TOTP and OCRA (RFC\u0026nbsp;4226/6238/6287) using deterministic secrets and fixtures.\n- Emulates EMV/CAP cardholder verification flows for lab, integration, and IAM workloads.\n- Exercises FIDO2/WebAuthn assertions and EUDIW OpenID4VP wallet/verifier exchanges with synthetic PID artefacts.\n- Provides five consumption surfaces:\n  - Native Java API entry points (per protocol).\n  - REST API (Spring Boot, OpenAPI-documented).\n  - CLI (Picocli commands for credential lifecycle and evaluation).\n  - Operator console UI for exploratory use.\n  - MCP proxy tools for agent/automation integrations (Model Context Protocol).\n\nTypical use cases include:\n\n- Generating OTPs, assertions, and related responses as part of simulated customer authentication flows in IAM systems.\n- Re-evaluating stored OTP/assertion payloads and shared secrets to validate cryptographic traces for non-repudiation.\n- Seeding credentials for consuming systems, allowing presets to be loaded without exposing underlying secrets while those systems can still generate OTPs and related results.\n\nOn a representative workload, the REST inline endpoints sustain:\n\n- HOTP/TOTP/OCRA/EMV: ~3.4k–6.6k requests/sec with p95 ≲18 ms and p99 ≲28 ms.\n- FIDO2/WebAuthn inline assertions: ~2.4k requests/sec with p95 ≈25 ms.\n- EUDIW OpenID4VP wallet simulation + validation: ~3.7k–3.9k requests/sec with p95 ≈15–16 ms.\n\nSee [REST inline performance baselines](docs/3-reference/rest-inline-performance-baselines.md) for the detailed benchmark table and environment notes.\n\nLicensed under the terms in [LICENSE](LICENSE).\n\n## Current status (2025-11-16)\n\nAll major protocol simulators are ready for lab and tooling scenarios; highlights per module:\n\n- ✅ `core` implements protocol primitives and fixtures for HOTP, TOTP, OCRA, FIDO2/WebAuthn, EMV/CAP, and EUDIW OpenID4VP.\n- ✅ `application` exposes orchestration services and Native Java API seams (for example `HotpEvaluationApplicationService`, `TotpEvaluationApplicationService`, `OcraEvaluationApplicationService`, `EmvCapEvaluationApplicationService`, `WebAuthnEvaluationApplicationService`, `OpenId4VpWalletSimulationService`, `OpenId4VpValidationService`).\n- ✅ `cli` ships Picocli commands for importing, listing, deleting, evaluating credentials, running MapDB maintenance tasks, and exercising fixtures across protocols.\n- ✅ `rest-api` exposes JSON endpoints for the simulators, publishes OpenAPI snapshots, and serves Swagger UI at `http://localhost:8080/swagger-ui/index.html` when booted locally.\n- ✅ `ui` hosts the operator console at /ui/console, reusing REST endpoints for inline and stored-credential evaluations.\n- ✅ Documentation under `docs/` covers Java integrations, CLI usage, REST operations, Native Java usage from tools (JMeter/Neoload), test vector generation, and persistence tuning.\n\n### Protocol reference\n\nProtocol-specific behaviour, parameters, and trace fields are documented under:\n\n- [HOTP](docs/3-reference/protocols/hotp.md)\n- [TOTP](docs/3-reference/protocols/totp.md)\n- [OCRA](docs/3-reference/protocols/ocra.md)\n- [FIDO2/WebAuthn](docs/3-reference/protocols/fido2-webauthn.md)\n- [EMV/CAP](docs/3-reference/protocols/emv-cap.md)\n- [EUDIW OpenID4VP](docs/3-reference/protocols/eudiw-openid4vp.md)\n\nPair these references with the how-to guides under [docs/2-how-to](docs/2-how-to) for end-to-end usage patterns.\n\n## Module map\n\n| Module       | Purpose                                                                                       |\n|--------------|-----------------------------------------------------------------------------------------------|\n| `core`       | Protocol primitives (HOTP/TOTP/OCRA, FIDO2/WebAuthn, EMV/CAP, EUDIW helpers), crypto, fixtures |\n| `application`| Orchestration services and Native Java API seams for all protocols                            |\n| `cli`        | Picocli tooling for credential lifecycle, evaluation, maintenance, and simulator fixtures     |\n| `rest-api`   | Spring Boot facade exposing JSON endpoints and Swagger/OpenAPI documentation                  |\n| `ui`         | Server-rendered operator console built atop the REST API                                      |\n| `infra-persistence` | MapDB-based `CredentialStoreFactory` and persistence defaults                          |\n| `standalone` | Aggregates all simulator modules into the `openauth-sim-standalone` jar (no third-party deps bundled) |\n\n## Quickstart by surface\n\n### Native Java API (example: HOTP)\n\n```java\nimport io.openauth.sim.application.hotp.HotpEvaluationApplicationService;\nimport io.openauth.sim.application.hotp.HotpEvaluationApplicationService.EvaluationCommand;\nimport io.openauth.sim.infra.persistence.CredentialStoreFactory;\nimport io.openauth.sim.core.otp.hotp.HotpHashAlgorithm;\n\nvar store = CredentialStoreFactory.openInMemoryStore();\nvar service = new HotpEvaluationApplicationService(store);\n\nEvaluationCommand.Inline cmd = new EvaluationCommand.Inline(\n        \"3132333435363738393031323334353637383930\",\n        HotpHashAlgorithm.SHA1,\n        6,\n        0L,\n        Map.of(),\n        0,\n        0);\n\nString otp = service.evaluate(cmd).otp();\n```\n\nSee [docs/2-how-to/use-hotp-from-java.md](docs/2-how-to/use-hotp-from-java.md), [docs/2-how-to/use-totp-from-java.md](docs/2-how-to/use-totp-from-java.md), [docs/2-how-to/use-ocra-from-java.md](docs/2-how-to/use-ocra-from-java.md),\n[docs/2-how-to/use-emv-cap-from-java.md](docs/2-how-to/use-emv-cap-from-java.md), [docs/2-how-to/use-fido2-from-java.md](docs/2-how-to/use-fido2-from-java.md), and [docs/2-how-to/use-eudiw-from-java.md](docs/2-how-to/use-eudiw-from-java.md)\nfor full Native Java examples across all protocols.\n\n### CLI\n\n```bash\n./gradlew --no-daemon :cli:run --args=\"hotp evaluate --help\"\n```\n\nProtocol-specific CLI usage (HOTP/TOTP/OCRA/FIDO2/EMV/EUDIW) is documented under [docs/2-how-to](docs/2-how-to) guides (see the `*-cli-operations.md` files).\n\n### REST API and UI\n\n```bash\n./gradlew --no-daemon --init-script tools/run-rest-api.init.gradle.kts runRestApi\n```\n\n- Swagger UI: `http://localhost:8080/swagger-ui/index.html`\n- Operator console: `http://localhost:8080/ui/console`\n\nOpenAPI snapshots live under [docs/3-reference](docs/3-reference) and are enforced by the `OpenApiSnapshotTest` suite.\n\n### MCP proxy (agents)\n\n1. Start the REST facade (see above) so `/api/v1/**` endpoints are available.\n2. Create `~/.config/openauth-sim/mcp-config.yaml` (or pass `--config \u003cpath\u003e`). Minimal example:\n\n   ```yaml\n   baseUrl: http://localhost:8080\n   apiKey:\n   timeouts:\n     defaultMillis: 10000\n     hotp.evaluate: 15000\n   ```\n\n3. Run the MCP proxy: `./gradlew --no-daemon :tools-mcp-server:run --args=\"--config ~/.config/openauth-sim/mcp-config.yaml\"`.\n4. Connect an MCP-aware client (for example `npx @modelcontextprotocol/cli`) to the spawned process. The server streams JSON-RPC messages over stdin/stdout using the standard `Content-Length` framing. The `tools/list` catalogue advertises tools such as `hotp.evaluate`, `totp.evaluate`, `totp.helper.currentOtp`, `ocra.evaluate`, `emv.cap.evaluate`, `fido2.assertion.evaluate`, `eudiw.wallet.simulate`, `eudiw.presentation.validate`, and `fixtures.list`, each with JSON Schema input definitions, per-tool prompt hints, and version metadata.\n\nEach tool forwards the supplied JSON payload to the documented REST endpoint and returns the HTTP status/body to the MCP client, so assistants see precisely the same behaviour as human operators using the REST API or UI while also benefiting from the enriched MCP tool metadata.\n\n## Standalone distribution\n\n- Published artifact: **`io.github.ivanstambuk:openauth-sim-standalone`**, an aggregated jar that contains all simulator modules (CLI/REST/UI/MCP) while leaving external libraries (Spring Boot, Picocli, MapDB, etc.) as Maven dependencies.\n- Build and run locally:\n\n  ```bash\n  ./gradlew --no-daemon :standalone:jar\n  java -jar standalone/build/libs/openauth-sim-standalone-0.1.3.jar --help\n  ```\n\n  (Replace the version suffix with the current `VERSION_NAME` when running locally.) The manifest’s `Main-Class` points to the CLI launcher; REST/MCP facades remain available by running their entry points via `java -cp` and resolving dependencies declared in the published POM. The publication filters out internal modules so the POM only lists third-party libraries—consumers can exclude the ones they do not need or add replacements using [docs/3-reference/external-dependencies-by-facade-and-scenario.md](docs/3-reference/external-dependencies-by-facade-and-scenario.md).\n\n  Gradle (Kotlin DSL):\n\n  ```kotlin\n  dependencies {\n      implementation(\"io.github.ivanstambuk:openauth-sim-standalone:0.1.3\")\n  }\n  ```\n\n  Maven:\n\n  ```xml\n  \u003cdependency\u003e\n    \u003cgroupId\u003eio.github.ivanstambuk\u003c/groupId\u003e\n    \u003cartifactId\u003eopenauth-sim-standalone\u003c/artifactId\u003e\n    \u003cversion\u003e0.1.3\u003c/version\u003e\n  \u003c/dependency\u003e\n  ```\n\n- Example Gradle dependency snippet (Kotlin DSL):\n\n  ```kotlin\n  implementation(\"io.github.ivanstambuk:openauth-sim-standalone:\u003cversion\u003e\")\n  ```\n\nFor release and publishing mechanics, see [docs/5-operations/standalone-release-runbook.md](docs/5-operations/standalone-release-runbook.md).\n\n### Specification-Driven Development (SDD)\n\n\u003e AI-native codebase: all production feature code is generated by AI agents from specifications and runbooks, with humans acting as reviewers/owners rather than hand-writing implementation. That makes the SDD workflow non-negotiable.\n\n- Specifications live under `docs/4-architecture/features/\u003cNNN\u003e/spec.md` and describe the intended behaviour for each feature.\n- Each spec has a matching plan/tasks pair at `docs/4-architecture/features/\u003cNNN\u003e/plan.md` and `docs/4-architecture/features/\u003cNNN\u003e/tasks.md` that sequence tests-before-code increments.\n- Before changing behaviour, update the spec, stage failing tests, then implement the smallest viable increment and run `./gradlew --no-daemon spotlessApply check`.\n- For the full governance story, see [AGENTS.md](AGENTS.md) and the project constitution at [docs/6-decisions/project-constitution.md](docs/6-decisions/project-constitution.md), plus the [GitHub Spec Kit guidance](https://github.com/github/spec-kit/blob/main/spec-driven.md).\n\n## Documentation\n\nLong-form documentation lives in `/docs`:\n\n| Path                     | Highlights                                                   |\n|--------------------------|--------------------------------------------------------------|\n| `docs/0-overview`        | Product overview, glossary, scope                            |\n| `docs/1-concepts`        | Domain concepts, capability matrix, telemetry references     |\n| `docs/2-how-to`          | Operator guides for REST, CLI, Java integrations, UI usage   |\n| `docs/3-reference`       | Generated artifacts including OpenAPI snapshots              |\n| `docs/4-architecture`    | Specifications, feature plans, tasks, roadmap, knowledge map |\n| `docs/5-operations`      | Runbooks and analysis gate checklist                         |\n| `docs/6-decisions`       | ADRs, including the project constitution                     |\n| `docs/7-changelogs`      | Release notes / change log seeds                             |\n| `docs/8-compliance`      | Security \u0026 compliance posture (stub)                         |\n| `docs/_assets`           | Diagram sources and shared images                            |\n\nConsult the living [Implementation Roadmap](docs/4-architecture/roadmap.md) for future priorities, and see [AGENTS.md](AGENTS.md) for AI agent expectations. Contributions welcome—read [CONTRIBUTING.md](CONTRIBUTING.md) before raising PRs.\n\n### For AI assistants and agents\n\nIf you're running this repository alongside an AI assistant or agent:\n\n- Use [ReadMe.LLM](ReadMe.LLM) for a compact, LLM-oriented overview of protocols, Native Java entry points, and minimal examples.\n- Use [llms.txt](llms.txt) as the manifest of high-signal specs under `docs/4-architecture/features` when constructing context windows.\n- Follow [AGENTS.md](AGENTS.md) for governance, workflow, and guardrails before making changes or suggesting refactors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanstambuk%2Fopenauth-sim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivanstambuk%2Fopenauth-sim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanstambuk%2Fopenauth-sim/lists"}