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
Session locking and unlocking with a passphrase
Multi-identity support (switching between DIDs)
DWN registration with remote nodes

Installation

npm install @enbox/auth @enbox/agent

Basic usage

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

const agent = await EnboxAgent.create();
const auth = new AuthManager({ agent });

// Create a new identity
await auth.connect();

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

Connection flows

1. First-time setup

When no identity exists, connect() 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, connect() unlocks the vault and resumes the session.

3. Wallet connect

For cross-device identity sharing, use the wallet connect flow with permission scopes:

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

const permissions: ConnectPermissionRequest = {
  permissionScopes: [
    {
      interface: 'Records',
      method: 'Write',
      protocol: 'https://example.com/protocol',
    },
  ],
};

await auth.connect({ connectOptions: permissions });

4. Disconnect

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

5. Lock / Unlock

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

await auth.unlock('my-passphrase');
console.log(auth.state); // 'connected'

Events

The auth manager emits state change events:

auth.on('state-change', (newState) => {
  console.log('Auth state changed to:', newState);
});