User API

The User API provides methods for creating, authenticating, and managing user accounts in GUN. Each user is identified by a cryptographic key pair.

gun.user()

Get or create a user context. Only one user can be authenticated per GUN instance.

const gun = Gun();
const user = gun.user();

Get User by Public Key

// Access another user's public data
const alice = gun.user('alice_public_key');
alice.get('profile').once(data => {
  console.log(data);
});

user.create()

Create a new user account with an alias (username) and password.

Syntax

user.create(alias, password, callback, options)
user.create(pair, callback, options)

Parameters

alias (string): Username for the account
password (string): Password (minimum 8 characters)
pair (object): Optional pre-generated key pair
callback (function): Called when creation completes
options (object): Optional configuration
- check: Validate alias and password (default: true)
- already: Allow creating if alias exists (default: false)

Example

const gun = Gun();
const user = gun.user();

user.create('alice', 'SecurePass123', (ack) => {
  if (ack.err) {
    console.error('Error:', ack.err);
    // Possible errors:
    // "No user." - No alias provided
    // "Password too short!" - Less than 8 characters
    // "User already created!" - Alias already exists
  } else {
    console.log('User created!', ack.pub);
    // ack.ok = 0 (not waiting for disk acknowledgment)
    // ack.pub = user's public key
  }
});

How It Works

Validation: Checks alias exists and password is 8+ characters
Salt Generation: Creates a random 64-character salt
Proof of Work: Uses SEA.work() to derive a key from password + salt (PBKDF2, 100,000 iterations)
Key Pair Generation: Creates ECDSA and ECDH key pairs via SEA.pair()
Encryption: Encrypts private keys with the proof-of-work result
Storage: Saves user data at ~@alias and ~publicKey nodes

User Data Structure

Reference: ~/workspace/source/sea/create.js:56-74

{
  pub: 'user_public_signing_key',
  epub: 'user_public_encryption_key',
  alias: 'alice',
  auth: {
    ek: 'encrypted_private_keys',  // AES-GCM encrypted
    s: 'random_salt'                // 64-char random salt
  }
}

Using Pre-generated Key Pairs

const pair = await SEA.pair();
user.create(pair, 'password123456', (ack) => {
  console.log('User created with existing pair');
});

If no callback is provided, the user is automatically authenticated:

user.create('bob', 'MyPassword99');
// User is automatically logged in

user.auth()

Authenticate an existing user with alias and password, or with a key pair.

Syntax

user.auth(alias, password, callback, options)
user.auth(pair, callback, options)

Parameters

alias (string): Username
password (string): User password
pair (object): Key pair object with pub, priv, epub, epriv
callback (function): Called after authentication
options (object):
- retries: Number of retry attempts (default: 9)
- remember: Store credentials in sessionStorage (default: false)
- change: New password for password update

Example with Alias/Password

user.auth('alice', 'SecurePass123', (ack) => {
  if (ack.err) {
    console.error('Auth failed:', ack.err);
    // Possible errors:
    // "Wrong user or password."
    // "User cannot be found!"
  } else {
    console.log('Authenticated!', ack.sea);
    // ack contains the user's SEA credentials
  }
});

Example with Key Pair

Authentication with a key pair is more reliable:

const pair = {
  pub: 'public_key',
  priv: 'private_key',
  epub: 'encryption_public_key',
  epriv: 'encryption_private_key'
};

user.auth(pair, (ack) => {
  console.log('Authenticated with keypair');
});

Session Management

// Remember user in sessionStorage
user.auth('alice', 'password', (ack) => {
  console.log('Session stored');
}, { remember: true });

// Later, recall the session
user.recall({ sessionStorage: true });

Password Change

user.auth('alice', 'OldPassword123', (ack) => {
  console.log('Password updated!');
}, { change: 'NewPassword456' });

user.leave()

Log out the current user and clear session data.

Syntax

user.leave(options, callback)

Example

user.leave();

// Session cleared:
// - user.is deleted
// - user._.sea deleted
// - sessionStorage.recall deleted
// - sessionStorage.pair deleted

user.recall()

Restore a previously authenticated session from sessionStorage.

Syntax

user.recall(options, callback)

Example

const gun = Gun();
const user = gun.user().recall({ sessionStorage: true });

// User is auto-authenticated if session exists
gun.on('auth', () => {
  console.log('User restored from session');
});

user.is

Check if a user is currently authenticated.

Example

if (user.is) {
  console.log('User is logged in:', user.is.alias);
  console.log('Public key:', user.is.pub);
  console.log('Encryption key:', user.is.epub);
} else {
  console.log('No user authenticated');
}

Authentication Flow

Reference: ~/workspace/source/sea/auth.js:43-65 The authentication process:

Lookup: Find user data at ~@alias
Parse Auth: Extract encrypted credentials from auth.ek and auth.s
Proof of Work: Derive key from password + salt (PBKDF2)
Decrypt: Decrypt private keys using the derived key
Validate: Reconstruct key pair and verify
Session: Store credentials in memory and optionally in sessionStorage
Event: Emit ‘auth’ event on successful authentication

Private keys are encrypted with AES-GCM using a PBKDF2-derived key from your password. Never share your password or private keys. They cannot be recovered if lost.

Security Notes

Passwords must be at least 8 characters
Private keys are never stored in plaintext
PBKDF2 with 100,000 iterations protects against brute force
Session data is only stored if remember option is enabled
Authentication uses constant-time comparisons where possible

Common Patterns

user.create('newuser', 'password123456');
// No callback = auto-login after creation

Check Auth Status

if (user.is) {
  // User is authenticated
  user.get('profile').put({ status: 'online' });
}

Handle Auth Events

gun.on('auth', (ack) => {
  console.log('User authenticated:', ack.sea.pub);
});

Get Started

Core Concepts

API Reference

Security (SEA)

Storage Adapters

Advanced

Integration Guides

User API

User API

gun.user()

Get User by Public Key

user.create()

Syntax

Parameters

Example

How It Works

User Data Structure

Using Pre-generated Key Pairs

user.auth()

Syntax

Parameters

Example with Alias/Password

Example with Key Pair

Session Management

Password Change

user.leave()

Syntax

Example

user.recall()

Syntax

Example

user.is

Example

Authentication Flow

Security Notes

Common Patterns

Check Auth Status

Handle Auth Events

​User API

​gun.user()

​Get User by Public Key

​user.create()

​Syntax

​Parameters

​Example

​How It Works

​User Data Structure

​Using Pre-generated Key Pairs

​Auto-login After Creation

​user.auth()

​Syntax

​Parameters

​Example with Alias/Password

​Example with Key Pair

​Session Management

​Password Change

​user.leave()

​Syntax

​Example

​user.recall()

​Syntax

​Example

​user.is

​Example

​Authentication Flow

​Security Notes

​Common Patterns

​Registration + Auto-login

​Check Auth Status

​Handle Auth Events

User API

gun.user()

Get User by Public Key

user.create()

Syntax

Parameters

Example

How It Works

User Data Structure

Using Pre-generated Key Pairs

Auto-login After Creation

user.auth()

Syntax

Parameters

Example with Alias/Password

Example with Key Pair

Session Management

Password Change

user.leave()

Syntax

Example

user.recall()

Syntax

Example

user.is

Example

Authentication Flow

Security Notes

Common Patterns

Registration + Auto-login

Check Auth Status

Handle Auth Events