Authentication

How authentication works in Enbox — connect, lock, disconnect, and multi-identity flows.

Overview

@enbox/auth provides the AuthManager class that handles the full authentication lifecycle for Enbox applications. It manages:

Identity creation and agent bootstrapping
Wallet-based connection for cross-device identity sharing
Vault locking and session restoration with a passphrase
Multi-identity support (switching between DIDs)
DWN registration with remote nodes

Installation

npm install @enbox/auth @enbox/agent
npm install @enbox/browser # for browser wallet-connect handlers

Basic usage

import { AuthManager } from '@enbox/auth';

const auth = await AuthManager.create({ password: userPassword });

// Create a new identity
const session = await auth.connectVault({ createIdentity: true });

// Check connection state
console.log(auth.state); // 'connected'
console.log(session.did); // 'did:dht:...'

Connection flows

1. First-time setup

When no identity exists, connectVault({ createIdentity: true }) creates a new DID, generates encryption keys, and bootstraps the agent with a local DWN.

2. Returning user

If an identity already exists in the vault, connectVault() unlocks the vault and resumes the session.

For cross-device identity sharing, configure an AuthManager with a connectHandler and request the protocols you need. The handler drives the permission-scope UX (e.g. via a browser overlay) and returns a delegate session bound to the connecting wallet.

import { AuthManager } from '@enbox/auth';
import { BrowserConnectHandler } from '@enbox/browser';

const walletAuth = await AuthManager.create({
  connectHandler: BrowserConnectHandler({ appName: 'Notes App' }),
});

const session = await walletAuth.connect({ protocols: [NotesProtocol] });

4. Disconnect

await auth.disconnect();
console.log(auth.state); // 'unlocked'

5. Lock / Unlock

await auth.lock();
console.log(auth.state); // 'locked'

await auth.restoreSession({ password: 'my-passphrase' });
console.log(auth.state); // 'connected'

Events

The auth manager emits state change events. The handler receives a payload with the previous and current states:

auth.on('state-change', ({ previous, current }) => {
  console.log(`Auth state changed: ${previous} → ${current}`);
});