zklservices.t3rdwl

Standalone zkLogin service for the Sui ecosystem - OAuth auth, deterministic salts, and Groth16 proving. Derives Sui addresses from Google/Apple IDs (more providers in future). Runs its own DB. Uses Mysten cloud prover by default; Docker rapidsnark or snarkjs when configured.

Quick Start

# 1. Start PostgreSQL
docker compose -f docker-compose.db.yml up -d

# 2. Configure .env (copy from .env.example, add Google OAuth creds)
cp .env.example .env

# 3. Install & run
npm install
npm run dev

Service starts on http://localhost:4001.

Environment

Key	Default	Description
PORT	4001	Service port
SELF_URL	http://localhost:4001	Public URL of this service (used for OAuth redirects)
FRONTEND_URL	http://localhost:3000	Global fallback frontend URL - overridden per-dApp by API key's frontend_url
DB_MODE	demo	demo (local Docker) or live (DATABASE_URL)
DATABASE_URL	-	Neon/RDS connection string (when DB_MODE=live)
JWT_SECRET	-	Secret for deterministic salt derivation - don't change once users exist
ADMIN_API_KEY	-	Bootstrap API key (bypasses DB)
SUI_NETWORK	testnet	Sui network - auto-derives RPC, epoch, gRPC
SUI_RPC_URL	auto	Override; default is https://fullnode.{network}.sui.io:443
PROVER_MODE	proxy	proxy, docker, snarkjs, or auto
PROXY_PROVER_URL	https://prover-dev.mystenlabs.com/v1	Mysten cloud prover (accepts custom aud)
DOCKER_PROVER_URL	http://localhost:8080	Local rapidsnark prover URL
ZKEY_PATH	./keys/zkLogin-main.zkey	Path to snarkjs zkey file
WASM_PATH	./keys/zkLogin-main.wasm	Path to snarkjs wasm file
GOOGLE_CLIENT_ID	-	Google OAuth client ID
GOOGLE_CLIENT_SECRET	-	Google OAuth client secret
GOOGLE_AUTH_URL	https://accounts.google.com/o/oauth2/v2/auth	Override Google auth endpoint
GOOGLE_TOKEN_URL	https://oauth2.googleapis.com/token	Override Google token endpoint
GOOGLE_ISSUER	https://accounts.google.com	Override Google JWT issuer
GOOGLE_JWKS_URL	https://www.googleapis.com/oauth2/v3/certs	Override Google JWKS URL
APPLE_CLIENT_ID	-	Apple OAuth client ID
APPLE_TEAM_ID	-	Apple Developer team ID
APPLE_KEY_ID	-	Apple p8 key ID
APPLE_PRIVATE_KEY	-	Apple p8 private key contents
APPLE_PRIVATE_KEY_PATH	-	Path to Apple p8 private key file (alternative to inline above)
APPLE_AUTH_URL	https://appleid.apple.com/auth/authorize	Override Apple auth endpoint
APPLE_TOKEN_URL	https://appleid.apple.com/auth/token	Override Apple token endpoint
APPLE_ISSUER	https://appleid.apple.com	Override Apple JWT issuer
APPLE_JWKS_URL	https://appleid.apple.com/auth/keys	Override Apple JWKS URL

Architecture

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│   Frontend   │────▶│  zklservices     │────▶│  PostgreSQL  │
│  (dApp SPA)  │     │  (port 4001)     │     │  (port 5433) │
└──────────────┘     ├──────────────────┤     └──────────────┘
                     │  OAuth exchange  │
                     │  Salt derivation │     ┌──────────────┐
                     │ JWT verification │────▶│  Mysten      │
                     │  Groth16 proving │     │  Prover API  │
                     └──────────────────┘     └──────────────┘

See docs/architecture.md and docs/api.md.

License

GNU General Public License v3.0 - see LICENSE.