Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
269 lines (209 loc) · 8.44 KB

GETTING_STARTED.md

File metadata and controls

269 lines (209 loc) · 8.44 KB
Raw

Getting Started with aZKey

Overview

aZKey is a privacy-preserving authentication system for Aztec Network that allows users to:

  • Create accounts using familiar Web2 identity providers (Google)
  • Recover accounts without seed phrases
  • Maintain privacy through zero-knowledge proofs
  • Control accounts with session owners (ephemeral keys)

Quick Start (5 minutes)

Option 1: Try the Live Demo

# Coming soon - demo will be deployed at azkey.example.com

Option 2: Run Locally

# Clone the repository
git clone https://github.com/eth-ecuador/aZKey.git
cd aZKey

# Install dependencies
pnpm install

# Start the dev interface
cd apps/interface
pnpm dev

# Open http://localhost:5173 in your browser

Integration into Your App

Install the SDK

npm install azkey-sdk
# or
pnpm add azkey-sdk

Basic Usage

import { AccountManager } from 'azkey-sdk';

const accountManager = new AccountManager({
  googleClientId: process.env.GOOGLE_CLIENT_ID!,
  googleClientSecret: process.env.GOOGLE_CLIENT_SECRET,
  aztecRpcUrl: process.env.AZTEC_RPC_URL || 'http://localhost:8080',
  redirectUri: 'https://yourapp.com/oauth/callback'
});

// Start OAuth flow
const authUrl = accountManager.getAuthUrl();
window.location.href = authUrl;

// Handle callback
const code = new URLSearchParams(window.location.search).get('code');
const authResult = await accountManager.exchangeCode(code);

// Create account
const accountInfo = await accountManager.createAccount(authResult);
console.log('Account created at:', accountInfo.address);
console.log('Session owner:', accountInfo.sessionOwner);

How It Works

1. Authentication

User authenticates with Google OAuth, receiving a JWT token.

2. Account ID Derivation

The SDK derives a permanent account_id from the JWT:

account_id = hash(jwt.sub, jwt.aud)
  • jwt.sub = Google's unique user ID (private)
  • jwt.aud = Your app's OAuth client ID
  • This hash is deterministic and consistent

3. Proof Generation

Client-side Noir circuit generates a ZK proof that:

  • ✓ The JWT signature is valid (verified with Google's public key)
  • ✓ The account_id matches hash(sub, aud)
  • ✓ Private inputs (JWT content, Google key) stay off-chain

4. Account Deployment

Smart contract is deployed with the account_id stored immutably.

5. Session Management

A temporary session_owner (ephemeral key) is authorized to control the account:

  • Users sign transactions with this temporary key
  • If lost, users can recover with Google OAuth and set a new session owner
  • The account_id ensures the same person recovers their own account

Architecture

┌─────────────────────────────────────────────────────────┐
│                   User's Browser                         │
├──────────────────┬──────────────────┬──────────────────┤
│  Google OAuth    │  SDK              │  Interface       │
│  (Google.com)    │  (azkey-sdk)       │  (SvelteKit)    │
└──────────────────┴──────────────────┴──────────────────┘
         │                  │                  │
         ├──────────────────┴──────────────────┤
         │                                      │
         v                                      v
    ┌──────────────────┐          ┌───────────────────────┐
    │ Google OAuth      │          │ Proof Generator       │
    │ (JWT Issuance)    │          │ (Noir Client)         │
    │                   │          │                       │
    │ Returns: JWT      │          │ Generates: ZK Proof   │
    └──────────────────┘          └───────────────────────┘
         │                                  │
         └──────────────────┬───────────────┘
                            │
                            v
         ┌──────────────────────────────────┐
         │     Aztec Network (L2)            │
         ├──────────────────────────────────┤
         │  JWT Account Contract             │
         │  - Stores account_id (immutable)  │
         │  - Stores session_owner (mutable) │
         │  - Verifies ZK proofs             │
         └──────────────────────────────────┘

Environment Variables

# Google OAuth
VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
VITE_GOOGLE_CLIENT_SECRET=your-client-secret

# Aztec Network
VITE_AZTEC_RPC_URL=http://localhost:8080  # or Aztec testnet RPC

# Callback URL
VITE_REDIRECT_URI=http://localhost:5173/oauth/callback

Development

Run Interface

cd apps/interface
pnpm dev

Build SDK

cd packages/sdk
pnpm build

Run Tests

# Unit tests
pnpm test:unit

# Integration tests (requires Aztec sandbox)
RUN_INTEGRATION_TESTS=true pnpm test:integration

# E2E tests
RUN_E2E_TESTS=true pnpm test:e2e

Project Structure

aZKey/
├── apps/
│   └── interface/           # SvelteKit demo app
│       ├── src/
│       │   ├── routes/      # Page routes (home, create-account, etc.)
│       │   └── lib/         # Components (GoogleSignIn, etc.)
│       └── package.json
├── packages/
│   ├── sdk/                 # TypeScript SDK
│   │   ├── src/
│   │   │   ├── account/     # Account manager
│   │   │   ├── proof/       # Proof generation
│   │   │   ├── providers/   # OAuth providers (Google, etc.)
│   │   │   └── aztec/       # Aztec client
│   │   └── package.json
│   └── contracts/           # Noir circuits (under development)
│       └── noir/
│           ├── jwt/         # JWT parsing and verification
│           └── jwt_account/ # Main account circuit
├── AGENTS.md                # Commands reference
├── README.md                # Project overview
└── GETTING_STARTED.md       # This file

Common Tasks

Add a New OAuth Provider

  1. Create packages/sdk/src/providers/apple.ts:
import { BaseProvider } from './base';

export class AppleProvider extends BaseProvider {
  // Implement getAuthUrl(), exchangeCode(), etc.
}

  1. Update AccountManager to support the new provider

  2. Test with the interface

Deploy to Production

  1. Set real Google OAuth credentials
  2. Point to Aztec mainnet RPC
  3. Deploy interface to Vercel: vercel deploy
  4. Publish SDK: npm publish

Run Aztec Sandbox Locally

# Install Aztec
npm install -g @aztec/cli

# Start sandbox
aztec-nargo sandbox

# Interface will connect to http://localhost:8080

Troubleshooting

"Google OAuth not working"

  • Check VITE_GOOGLE_CLIENT_ID in .env.local
  • Ensure redirect URI matches in Google Cloud Console
  • Browser console should show Google SDK loading

"Account creation fails"

  • In demo mode, should work without Aztec
  • For real contracts, ensure Aztec RPC is accessible
  • Check network tab for failed requests

"SDK import errors"

  • Run pnpm install to ensure dependencies
  • SDK must be built: cd packages/sdk && pnpm build
  • Check TypeScript types with pnpm check

Next Steps

  • Read the API Reference for SDK methods
  • Explore Architecture for technical details
  • Check Examples for integration patterns
  • Join the community - GitHub Discussions coming soon

Support

License

MIT - See LICENSE file