{"id":47577856,"url":"https://github.com/subc0der/midnight-authenticator","last_synced_at":"2026-04-15T04:00:34.313Z","repository":{"id":345855045,"uuid":"1185714438","full_name":"subc0der/midnight-authenticator","owner":"subc0der","description":"Zero-knowledge TOTP authenticator for Midnight blockchain","archived":false,"fork":false,"pushed_at":"2026-03-31T01:40:26.000Z","size":6093,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-31T04:12:30.515Z","etag":null,"topics":["compact","midnightntwrk"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/subc0der.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-03-18T21:49:27.000Z","updated_at":"2026-03-31T01:40:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/subc0der/midnight-authenticator","commit_stats":null,"previous_names":["subc0der/midnight-authenticator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/subc0der/midnight-authenticator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subc0der%2Fmidnight-authenticator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subc0der%2Fmidnight-authenticator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subc0der%2Fmidnight-authenticator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subc0der%2Fmidnight-authenticator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/subc0der","download_url":"https://codeload.github.com/subc0der/midnight-authenticator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subc0der%2Fmidnight-authenticator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31825515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"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":["compact","midnightntwrk"],"created_at":"2026-03-31T07:00:24.934Z","updated_at":"2026-04-15T04:00:34.300Z","avatar_url":"https://github.com/subc0der.png","language":"TypeScript","funding_links":[],"categories":["Identity \u0026 Privacy"],"sub_categories":[],"readme":"# Midnight Authenticator\n\n\u003e Built on the [Midnight Network](https://midnight.network)\n\n**Zero-knowledge TOTP authenticator for the Midnight blockchain.**\n\n*Prove you have the right code without showing it.*\n\nMidnight Authenticator enables users to prove they possess a valid authentication code without revealing the underlying secret or the code itself. Unlike traditional 2FA where codes are transmitted in plaintext, this authenticator replaces codes with zero-knowledge proofs - privacy-preserving 2FA that doesn't leak secrets to verifiers.\n\n**Contract deployed on Preprod:** [`02b325...1d66`](https://preprod.midnightexplorer.io/contract/02b3255950655d5c3f2695692e8135c1c4119240c64a6abfe92bdafbc1751d66)\n\n## Screenshots\n\n| Extension | Demo dApp |\n|-----------|-----------|\n| ![Extension](Extension.png) | ![Demo App](DemoApp.png) |\n\n## Important: ZK-Native Protocol\n\nThis authenticator uses Midnight's `persistentHash` for code generation, making it a **ZK-native protocol**. It is **NOT RFC 6238 (TOTP) compatible**.\n\n| Aspect | Standard TOTP | Midnight Authenticator |\n|--------|---------------|------------------------|\n| Hash function | HMAC-SHA1 | persistentHash (ZK-friendly) |\n| Interoperability | Works with Google Auth, etc. | Standalone ZK system |\n| Privacy | Codes transmitted in plaintext | Codes never transmitted (ZK proof instead) |\n| Verification | Server compares codes | Server verifies ZK proof |\n\nCodes displayed in this app will **NOT match** standard authenticators like Google Authenticator.\n\n## Status\n\n**Phase 4: ZK Integration** - Mainnet Ready\n\n| Component | Status | Notes |\n|-----------|--------|-------|\n| Compact Contract | ✅ Deployed | `totp-verifier.compact` on preprod |\n| TypeScript Bindings | ✅ Generated | Full type-safe API |\n| Chrome Extension | ✅ MVP Complete | Encrypted vault, ZK code generation (mock proofs in dev, see below) |\n| Proof Provider | ✅ Architecture Ready | Lace wallet integration for mainnet |\n| Security Reviews | ✅ 9 Reviews | All issues addressed |\n| Test Coverage | ✅ 129 Tests | Vault, backup, accounts, crypto |\n\n### Proof Generation\n\n| Component | Proof Type | Notes |\n|-----------|------------|-------|\n| **Deploy CLI** (Node.js) | Real ZK proofs | Uses Docker proof server |\n| **Browser Extension** | Mock proofs | SDK browser limitation (same as all Midnight extensions) |\n| **Mainnet** | Real ZK proofs | Via Lace wallet integration |\n\n**For developers testing real ZK proofs:**\n\n```bash\n# Start proof server\ndocker run -d --name proof-server -p 6300:6300 \\\n  midnightntwrk/proof-server:8.0.3 midnight-proof-server -v\n\n# Deploy contract with real ZK proofs\ncd packages/deploy-cli\nMIDNIGHT_SEED=\"your64hexseed\" pnpm deploy\n```\n\nThe browser extension uses mock proofs during development because the Midnight SDK doesn't yet support browser-based proof generation. This is a known limitation shared by all Midnight browser extensions. At mainnet, users with Lace wallet will automatically use real proofs via Midnight's hosted infrastructure.\n\n**Security note:** Mock proofs are for development/testing only. They do NOT provide ZK privacy or cryptographic integrity guarantees. Never use mock proofs with real credentials or in production scenarios.\n\n## Features\n\n- Zero-knowledge authentication using Midnight's ZK proof system\n- ZK-native code generation (`persistentHash`)\n- Encrypted local vault (Argon2id + AES-256-GCM)\n- Encrypted backup/restore with password protection\n- Chrome extension (Manifest V3)\n- Real-time countdown timer (30-second windows)\n- Click-to-copy codes\n- Auto-lock security timer (5 minutes)\n- Dark theme UI\n\n## How It Works\n\n### Traditional TOTP Problem\n- Service stores shared secrets (can be leaked)\n- Codes transmitted in plaintext (can be intercepted)\n- Service knows exact authentication times\n\n### ZK Solution\n- User proves: \"I know secret S that produces a valid auth code\"\n- Service only learns: \"user authenticated successfully\"\n- Secret never leaves the user's device\n- Code never transmitted - replaced by ZK proof\n\n### Protocol Flow\n\n1. **Registration**: User commits `persistentCommit(secret, blinder)` on-chain\n2. **Authentication**: User generates ZK proof showing knowledge of secret\n3. **Verification**: Contract verifies proof without learning secret or code\n\n## Packages\n\n```\npackages/\n  contracts/        Compact smart contracts (ZK circuits)\n  core/             Core SDK and proof generation\n  extension/        Chrome extension (wallet + authenticator)\n```\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+\n- pnpm 9+\n- Docker (for proof server)\n- WSL (Windows only, for Compact CLI)\n\n### Setup\n\n```bash\ngit clone https://github.com/subc0der/midnight-authenticator.git\ncd midnight-authenticator\npnpm install\n```\n\n### Start Proof Server\n\n```bash\ndocker run -d --name proof-server -p 6300:6300 \\\n  midnightntwrk/proof-server:8.0.3 midnight-proof-server -v\n\n# Verify it's running\ncurl http://localhost:6300/version\n```\n\n### Build\n\n```bash\n# Build all packages\npnpm build\n\n# Build contracts only (requires WSL on Windows)\npnpm build:contracts\n\n# Build extension\npnpm --filter @midnight-authenticator/extension build\n```\n\n### Load Extension\n\n1. Open Chrome and navigate to `chrome://extensions`\n2. Enable \"Developer mode\"\n3. Click \"Load unpacked\"\n4. Select `packages/extension/dist`\n\n## Quick Start\n\nAfter loading the extension:\n\n1. Click the extension icon\n2. Create a vault password\n3. Add an account:\n   - Issuer: `TestService`\n   - Name: `user@example.com`\n   - Secret: `JBSWY3DPEHPK3PXP` (any Base32 string)\n4. Click the account to reveal the ZK auth code\n5. The code refreshes every 30 seconds\n\n**Note**: These codes are ZK-native and will NOT match Google Authenticator.\n\n## Backup \u0026 Restore\n\nYour accounts are stored in an encrypted vault. To prevent data loss:\n\n1. Click the **Export Backup** button\n2. Enter a strong password (8+ characters, 2+ character types)\n3. Save the encrypted `.json` file securely\n\nTo restore from backup:\n\n1. Click **Import Backup**\n2. Select your backup file\n3. Enter the backup password\n4. Choose **Merge** (add to existing) or **Replace** (overwrite all)\n\n**Security notes:**\n- Backup files are encrypted with PBKDF2 (600k iterations) + AES-256-GCM\n- The extension shows a warning if you haven't backed up recently\n- Backups contain secrets - store them securely (password manager, encrypted drive)\n\n## Contract Architecture\n\nThe `totp-verifier.compact` contract provides:\n\n| Circuit | Purpose |\n|---------|---------|\n| `registerAccount` | Register commitment on-chain |\n| `authenticate` | Prove knowledge of secret for time window |\n| `isRegistered` | Check if account exists |\n| `computeAuthCode` | Pure circuit for client-side code generation |\n\n### Security Model\n\n- **Commitment**: `persistentCommit(secret, blinder)` stored on-chain\n- **Auth Proof**: `persistentHash(authCode, blinder, nonce)` for unlinkability\n- **Time Window**: Public input from verifier (30-second intervals)\n- **Replay Protection**: Monotonic nonce per account\n\n### What's Private vs Public\n\n| Data | Visibility | Notes |\n|------|------------|-------|\n| accountId | Public | Identifies the account |\n| nonce | Public | Replay protection |\n| expectedTimeWindow | Public | Verifier-provided |\n| secret | **Private** | Never revealed |\n| blinder | **Private** | Commitment scheme |\n| authCode | **Private** | Computed but never transmitted |\n\n## Technology\n\n| Layer | Technology |\n|-------|------------|\n| Smart Contracts | Compact (Midnight ZK language) |\n| Extension | React + Vite, Chrome MV3 |\n| Encryption | Argon2id + AES-256-GCM |\n| ZK Proofs | Midnight proof server (via Lace or Docker) |\n| Code Generation | `persistentHash` (ZK-friendly) |\n| Network | Midnight Preprod → Mainnet |\n\n### SDK Versions (Ledger v8)\n\n| Package | Version |\n|---------|---------|\n| `@midnight-ntwrk/compact-runtime` | 0.15.0 |\n| `@midnight-ntwrk/midnight-js-contracts` | 4.0.2 |\n| `@midnight-ntwrk/ledger` | 4.0.0 |\n| Proof Server | 8.0.3 |\n| Compact CLI | 0.5.0 |\n\n## Project Structure\n\n```\nmidnight-authenticator/\n  packages/\n    contracts/              Compact contracts\n      src/\n        totp-verifier.compact   ZK authentication circuit\n        managed/                Compiled output (zkir, keys, TS bindings)\n    core/                   Core SDK\n      src/\n        index.ts            Exports and utilities\n    extension/              Chrome extension\n      src/\n        popup/              React UI\n        background/         Service worker (auth code, vault)\n        content/            Page integration\n```\n\n## Development\n\n### Compile Contracts (WSL required on Windows)\n\n```bash\ncd packages/contracts\npnpm compile\n```\n\n### Run Extension in Dev Mode\n\n```bash\ncd packages/extension\npnpm dev\n```\n\n### Run Tests\n\n```bash\npnpm test              # Run all tests\npnpm test --coverage   # With coverage report\n```\n\nTest coverage includes:\n- Vault encryption/decryption (22 tests)\n- Base32 encoding (24 tests)\n- Password validation (15 tests)\n- Backup/restore (14 tests)\n- Account CRUD (54 tests)\n\n## Roadmap\n\n### Completed\n\n- [x] **Phase 1: Research \u0026 Foundation**\n  - ZK-compatible approach using `persistentHash`\n  - Circuit architecture design\n  - Monorepo setup\n\n- [x] **Phase 2: Core Circuits**\n  - `totp-verifier.compact` with 9 security reviews\n  - Compact CLI compilation (3 circuits)\n  - TypeScript bindings generated\n\n- [x] **Phase 3: Extension MVP**\n  - Encrypted vault (Argon2id + AES-256-GCM)\n  - ZK auth code generation via pure circuits\n  - Account management UI with auto-lock\n\n- [x] **Phase 4: ZK Integration**\n  - Contract deployed to preprod\n  - Proof provider architecture (Lace, Docker, Mock)\n  - Vault-locked authentication flow\n  - Demo verifier dApp\n\n### In Progress\n\n- [ ] **Phase 5: Production**\n  - Mainnet deployment (pending mainnet launch)\n  - Chrome Web Store submission\n  - End-to-end testing with real ZK proofs\n\n## Demo dApp\n\nA demo verifier application is included to test the authentication flow:\n\n```bash\ncd apps/demo\npnpm dev\n```\n\n1. Open the demo at `http://localhost:5173`\n2. Add an account in the extension\n3. Copy the Account ID from the extension (click the ID below the code)\n4. Paste into the demo and click \"Request Authentication\"\n5. Approve in the extension popup\n6. See the ZK proof result\n\n## Architecture\n\n```\n┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐\n│   Demo dApp     │────▶│    Extension    │────▶│  Proof Server   │\n│  (Verifier)     │     │  (Prover/User)  │     │  (Lace/Docker)  │\n└─────────────────┘     └─────────────────┘     └─────────────────┘\n        │                       │                       │\n        │  AUTH_REQUEST         │  Generate ZK Proof    │\n        │◀──────────────────────│◀──────────────────────│\n        │                       │                       │\n        ▼                       ▼                       ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                    Midnight Network (Preprod)                    │\n│            Contract: 02b3255950655d5c3f2695692e8135...          │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## Resources\n\n- [Midnight Developer Docs](https://docs.midnight.network/develop/tutorial)\n- [Compact Language](https://docs.midnight.network/develop/tutorial/high-level-arch)\n- [Midnight Releases](https://releases.midnight.network/)\n- [Preprod Explorer](https://preprod.midnightexplorer.io/)\n\n## Contributing\n\nContributions welcome! This project has undergone multiple security-focused code reviews. Key patterns:\n- All auth requests require explicit user approval (no silent proof generation)\n- Secrets zeroed after use (`secret.fill(0)`)\n- Origin validation via `sender.origin`, not message payload\n- Keyboard accessibility for all interactive elements\n\n## License\n\nApache 2.0 - See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubc0der%2Fmidnight-authenticator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsubc0der%2Fmidnight-authenticator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubc0der%2Fmidnight-authenticator/lists"}