Identity Rollout Playbook

Last updated 25 Jan 2026, 13:49

Operators can authenticate using multiple methods in the Zenpower ecosystem:

  1. Email-First (Recommended) — Start with email registration and verification. This is the primary onboarding path that unlocks basic access without requiring Web3 knowledge.
  2. Sign-In with Ethereum (SIWE) — For advanced users, connect a MetaMask wallet for full ecosystem access, including on-chain identity and premium features.
  3. Keycloak SSO (Legacy) — Traditional OAuth2/OIDC flows for operators transitioning from existing identity providers.

Use this playbook to coordinate the rollout across dev, staging, and production.

Scope

  • Surfaces — admin.zenpower.at, status.zenpower.at, landing portals, API docs/swagger, ZenControl CLI.
  • Backends — apps/api FastAPI service (wallet endpoints), Traefik forward-auth, Keycloak.
  • Wallet tooling — MetaMask, WalletConnect (optional), zenctl CLI helpers.

Phased Rollout

Dev PC / WSL (Environment assignment: dev PC / WSL)

  1. Keep SIWE_ENABLED=0 in .env.devpc while developing.
  2. Implement and test nonce + verification endpoints locally (make api-wallet-smoke once implemented).
  3. Verify CLI flow:
    • Run zenctl auth wallet --dry-run to ensure the helper opens a browser and returns a mock token.
    • Capture transcripts under docs/status/sessions/ with timestamps.
  4. Update docs (wallet-auth-roadmap.md) after each milestone.

Staging Cluster

  1. Toggle SIWE_ENABLED=1 and SIWE_DOMAIN=staging.zenpower.at.
  2. Deploy updated frontend bundles with wallet CTA and ensure fallback login remains available.
  3. Log outcomes in logs/dispatch/wallet-auth-staging-<date>.md.
  4. Run browser-based manual tests (MetaMask signature success, rejection, cancellation).

Production Rollout

  1. Schedule maintenance window; announce change in docs/status/priorities.docs.json.
  2. Mirror staging config with production domain values.
  3. Update Keycloak realm to trust wallet-issued tokens (if bridging is required).
  4. Monitor logs for signature failures and replay attempts; keep SIWE_REPLAY_CAP=5.
  5. Document the switchover in docs/status/sessions/<date>-wallet-go-live.md.

Configuration Flags

Add these to .env.example and environment-specific files:

Variable Description Default
SIWE_ENABLED Enable wallet endpoints and frontend CTA 0
SIWE_DOMAIN Domain used in SIWE message (EIP-4361) zenpower.at
SIWE_ALLOWED_ORIGINS Comma-separated list for CORS https://*.zenpower.at
SIWE_MESSAGE_TEMPLATE Custom message suffix for signing prompt "Sign in to Zenpower Construct"
SIWE_SESSION_TTL_SECONDS Lifetime of wallet-backed session token 3600
SIWE_NONCE_TTL_SECONDS TTL for nonce storage 300

API Contract

  • POST /auth/wallet/nonce → 201 with {"nonce": "<hex>"} when SIWE is enabled.
  • POST /auth/wallet/verify expects address, signature, nonce, and the signed message (EIP-4361). Success returns 202 with {"token": "...", "address": "...", "issued_at": "...", "expires_at": "..."}.
  • Disabled environments respond with 501 for both endpoints; replayed or invalid signatures return 401.

Operator Checklist

  1. Ensure MetaMask is installed and pointing to the correct EVM-compatible network.
  2. Use zenctl auth wallet or web CTA to link wallet.
  3. Confirm identity in the UI (address, ENS badge, capability NFT status).
  4. Retain legacy Keycloak credentials as fallback until wallets are primary.
  5. Report issues via docs/status/sessions/ entries within 30 minutes.

Troubleshooting

  • Signature rejected — Validate nonce freshness, domain mismatch, and user signature. Rotate nonce cache if stuck.
  • Wallet not detected — Provide instructions for MetaMask installation or use legacy login.
  • Replay attack flagged — Ensure backend invalidates nonce after first use; investigate repeated attempts.
  • CLI headless usage — Use zenctl auth wallet --uri-only to copy the SIWE URL into another device for signing.

Documentation Tasks

  • Sync with docs/ops/wallet-auth-roadmap.md milestones.
  • Update docs/ops/forward-auth.md once Traefik headers are finalized.
  • Append wallet onboarding steps to docs/dev/ONBOARDING.md and docs/ops/security-segregation.md.
  • Add FAQs to docs/ops/runbooks/identity-wallet.md when established.
  • Coordinate front-end env vars (NEXT_PUBLIC_SIWE_DOMAIN, NEXT_PUBLIC_SIWE_URI, NEXT_PUBLIC_SIWE_CHAIN_ID, NEXT_PUBLIC_SIWE_STATEMENT) with backend defaults so the MetaMask flow matches API expectations (see apps/web/README.md).