## Overview


Identity Agents (IDA) are native desktop (Electron) or mobile (React Native) apps that are installed by end users to manage one or more decentralized identities.

## Launching an Identity Agent

Every time the Identity Agent launches, whether browser or mobile, the following code is run:

const agent = await IdentityAgent.create();
await agent.start({ passphrase: 'get-input' });

> **:lock: Note:**
> - The `passphrase` should likely be cached locally and periodically requested, similar to 1Password.
> - On mobile, face or fingerprint unlock could be used so that the `passphrase` doesn't have to be entered during every launch.

1. Check whether data vault is already initialized.
2. If not initialized, execute [First Launch](#First-Launch) process.
3. If already initialized, execute [Every Launch](#Every-Launch) process.

### First Launch

Since this is the first time the Identity Agent has run on this computing device, proceed to initialize or restore the data vault and agent DID.


1. Prompt end user to enter a passphrase.
2. An Ed25519 key pair is generated.
3. A did:key DID is created from the key pair generated in Step 2 (e.g., `did:key:ZM6abc123`). This DID will be subsequently referred to as the **Identity Agent DID**.
4. A non-secret static info value is combined with the Identity Agent DID public key as input to a Hash-based Key Derivation Function (HKDF) to derive a new 32-byte salt.
5. The salt value derived in Step 4 and the passphrase entered in Step 1 are used as input to the PBKDF2 algorithm to derive a secret key that will be referred to as the **Vault Unlock Key** (VUK).
6. The private key associated with the Identity Agent DID is encrypted using the derived VUK using XChaCha20-Poly1305 and the public key, salt, nonce, tag, and ciphertext are written to the AppDataVault store as a PBES2-HS512+XC20PKW JWE.
7. Cache the VUK in memory and set the data vault status to unlocked.
8. Set the Identity Agent's did:key identifier.
9. Import the Identity Agent's private key into the Identity Agent's KeyManager.

### Every Launch

1. Prompt end user to enter a `passphrase`.
2. The Identity Agent's salt value is read from the AppDataVault store.
3. The salt value retrieved in Step 2 and the passphrase entered in Step 1 are used as input to the PBKDF2 algorithm to derive the Vault Unlock Key (VUK).
4. Cache the VUK in memory and set the data vault status to unlocked.
5. Get the encrypted Identity Agent DID private key from the AppDataVault store (nonce, tag, and ciphertext) and decrypt it using the VUK.
6. Set the Identity Agent's did:key identifier.
7. Import the Identity Agent's private key into the Identity Agent's KeyManager.

## Creating Managed Identities

const career = await agent.identityManager.create({
  name      : 'Social',
  didMethod : 'ion',
  kms       : 'local'
});

const family = await agent.identityManager.create({
  name      : 'Social',
  didMethod : 'ion',
  kms       : 'local'
});

const social = await agent.identityManager.create({
  name      : 'Social',
  didMethod : 'ion',
  kms       : 'local'
});


## Working with Managed Identities

### Use the Web5 API

Instantiate a `Web5` instance by specifying the Identity Agent instance, `agent` and the DID of the Identity you want to use:

const web5 = new Web5({ agent, connectedDid: social.did });

Creating a record is the same Web5 API:

const { record, status } = await web5.dwn.records.create({
  data    : 'foo',
  message : {
    schema: 'bar/baz'
  }
})

### Managing Individual Identities

This is a contrived example, but here's the syntax for creating an additional `did:key` DID under the Social Identity's tenant:

const newDid = await agent.didManager.create({
  method: 'key',
  context: social.did
})

The `context` value indicates that you want the operations to be performed on the specified identity that the Identity Agent is managing.