> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavachos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# W3C DID identity

> Issue portable Ed25519-backed identities for agents using `did:key` or `did:web`. Agents sign payloads to prove identity across services without shared secrets.

## What are DIDs

W3C Decentralized Identifiers give agents a portable, cryptographic identity that works across services. Instead of an opaque token tied to one KavachOS instance, an agent gets a DID like `did:key:z6Mk...` backed by an Ed25519 keypair.

The agent can prove its identity to any service by signing a payload with its private key. The verifier resolves the DID to get the public key and checks the signature. No shared secrets, no central registry.

<Info>
  DIDs are optional. Regular `kv_` bearer tokens work fine for single-service deployments. Use DIDs when agents need to prove identity across organizational boundaries.
</Info>

## Two DID methods

KavachOS supports two W3C DID methods:

| Method    | Format                                    | Best for                                                                      |
| --------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
| `did:key` | `did:key:z6Mk...`                         | Self-contained identity. No server needed. Key is embedded in the identifier. |
| `did:web` | `did:web:auth.example.com:agents:agt_123` | Organization-backed identity. DID document hosted at a well-known URL.        |

## Generate a DID for an agent

<Tabs>
  <Tab title="did:key">
    ```typescript theme={"system"}
    const { agentDid, privateKeyJwk } = await kavach.did.generateKey(agent.id);

    console.log(agentDid.did);
    // did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

    // Store privateKeyJwk securely. It's shown once and never stored in the database.
    ```
  </Tab>

  <Tab title="did:web">
    Configure your domain first:

    ```typescript theme={"system"}
    const kavach = await createKavach({
      database: { provider: 'sqlite', url: 'kavach.db' },
      did: {
        web: { domain: 'auth.example.com', path: 'agents' },
      },
    });

    const { agentDid, privateKeyJwk } = await kavach.did.generateWeb(agent.id);

    console.log(agentDid.did);
    // did:web:auth.example.com:agents:agt_abc123
    ```

    Host the DID document at the resolved URL:

    ```
    did:web:auth.example.com:agents:agt_abc123
    → https://auth.example.com/agents/agt_abc123/did.json
    ```
  </Tab>
</Tabs>

<Warning>
  The private key is returned once and never stored in the database. Only the public key and DID document are persisted. Treat the private key like a bearer token.
</Warning>

## Sign and verify payloads

An agent can sign a payload to prove it authored a request:

```typescript theme={"system"}
// Agent signs a payload
const signed = await kavach.did.sign(agent.id, {
  action: 'deploy',
  environment: 'staging',
  timestamp: new Date().toISOString(),
}, privateKeyJwk);

console.log(signed.jws);    // compact JWS string
console.log(signed.issuer); // did:key:z6Mk...
```

A receiving service verifies the signature:

```typescript theme={"system"}
const result = await kavach.did.verify(signed.jws, agentDid.did);

if (result.valid) {
  console.log(result.payload);  // { action: 'deploy', ... }
  console.log(result.issuer);   // did:key:z6Mk...
}
```

## Verifiable presentations

A presentation is a signed JWT that bundles an agent's identity with its capabilities. Use this when an agent needs to prove both who it is and what it can do.

```typescript theme={"system"}
// Create a presentation
const jwt = await kavach.did.createPresentation({
  agentId: agent.id,
  did: agentDid.did,
  privateKeyJwk,
  capabilities: ['mcp:github:read', 'mcp:linear:write'],
  audience: 'https://mcp.partner.com',
  expiresIn: 300, // 5 minutes
});

// Verify on the receiving end
const result = await kavach.did.verifyPresentation(jwt);

if (result.valid) {
  console.log(result.agentId);      // agt_abc123
  console.log(result.capabilities); // ['mcp:github:read', 'mcp:linear:write']
}
```

## DID document structure

Every agent DID resolves to a W3C DID document:

```json theme={"system"}
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:key:z6MkhaXg...",
  "controller": "did:key:z6MkhaXg...",
  "verificationMethod": [{
    "id": "did:key:z6MkhaXg...#key-0",
    "type": "JsonWebKey2020",
    "controller": "did:key:z6MkhaXg...",
    "publicKeyJwk": {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "..."
    }
  }],
  "authentication": ["did:key:z6MkhaXg...#key-0"],
  "assertionMethod": ["did:key:z6MkhaXg...#key-0"],
  "capabilityInvocation": ["did:key:z6MkhaXg...#key-0"],
  "capabilityDelegation": ["did:key:z6MkhaXg...#key-0"]
}
```

## Retrieve a stored DID

```typescript theme={"system"}
const agentDid = await kavach.did.getAgentDid(agent.id);

if (agentDid) {
  console.log(agentDid.did);       // did:key:z6Mk...
  console.log(agentDid.method);    // 'key' or 'web'
}
```

## Resolve any DID

```typescript theme={"system"}
// Resolve did:key (local, no network)
const doc = await kavach.did.resolve('did:key:z6Mk...');

// Resolve did:web (fetches from HTTPS)
const doc = await kavach.did.resolve('did:web:auth.example.com');
```

<ParamField path="agentId" type="string">The agent this DID belongs to.</ParamField>
<ParamField path="did" type="string">The full DID string (did:key:... or did:web:...).</ParamField>
<ParamField path="method" type="'key' | 'web'">Which DID method was used.</ParamField>
<ParamField path="publicKeyJwk" type="JsonWebKey">Ed25519 public key in JWK format.</ParamField>
<ParamField path="didDocument" type="DidDocument">The full W3C DID document.</ParamField>
<ParamField path="createdAt" type="Date">When the DID was generated.</ParamField>

## Related

<CardGroup cols={2}>
  <Card title="Verifiable credentials" href="/verifiable-credentials" icon="circle-check">
    Issue W3C Verifiable Credentials backed by agent DIDs.
  </Card>

  <Card title="Agent identity federation" href="/federation" icon="network-wired">
    Cross-service agent authentication using signed federation tokens.
  </Card>

  <Card title="Agent identity" href="/agents" icon="robot">
    Bearer token identity and the agent lifecycle managed by KavachOS.
  </Card>

  <Card title="Standards alignment" href="/standards" icon="book-open">
    IETF draft claims KavachOS emits on agent JWTs.
  </Card>
</CardGroup>