# @ident-agency/agent

Agent layer for Ident.Agency - provides sandboxed iframe runtime and consent management for secure access to user data.

## Overview

Most likely you won't need to use this directly, but can instead use a web-component via the `@ident-agency/agent-ui` package.

This package builds on `@ident-agency/core` to enable secure, sandboxed access to encrypted at rest user data--fragments--through:

- **Sandboxed iframe runtime** - Isolated environment for crypto operations
- **Lens-based data access** - Safe, read-only views of user fragments
- **Consent management** - User-controlled permission grants
- **Storage adapters** - IndexedDB, memory, and cache implementations

## Architecture

The agent runs in a sandboxed iframe from `ident.agency` domain, ensuring:

- Keys and plaintext never exist in the host app's JavaScript context
- All cryptographic operations happen in the isolated agent environment

## Installation

```bash
npm install @ident-agency/agent
```

### Integration with Core

```typescript
import { createIA } from '@ident-agency/agent';
import { IndexedDBKV } from '@ident-agency/agent/adapters/indexeddb-kv';
import { PasswordProvider } from '@ident-agency/core';

// Initialize with real-world configuration
const passwordProvider = new PasswordProvider('secure-password');

const ia = await createIA({
	api: {
		baseUrl: 'https://www.ident.agency',
		redirectUri: window.location.origin,
		passwordProvider
	},
	storage: new IndexedDBKV('ia', 'kv'),
	ui: { mount: document.body },
	debug: true
});

// Listen for events
ia.on('subject_changed', (subject) => {
	console.log('Subject changed:', subject);
});

ia.on('grant_requested', (event) => {
	console.log('Grant requested:', event);
});
```

## Key Concepts

### Lenses

Lenses provide safe, read-only views of user data:

```typescript
// Request access to a specific data lens
const nameData = await ia.requestLens({
	path: '/identity/name',
	agent: { id: 'my-app' }
});
```

- Path-based access (e.g., `/identity/name`)
- User consent required for vault (encrypted) data
- No raw keys exposed to consuming applications

### Grants

Per-origin permission system:

```typescript
// Ensure grant for specific capabilities
await ia.ensureGrant({
	agent: { id: 'my-app' },
	manifest: {
		requested_capabilities: {
			read_lenses: ['/identity/*', '/wallet/xrpl/address'],
			mutate_paths: ['/preferences/*']
		}
	}
});

// Get current grants
const grants = await ia.getGrants({ agentId: 'my-app' });

// Revoke a grant
await ia.revokeGrant({ id: 'my-app' });
```

- Scoped access (e.g., `/wallets/xrpl/address`)
- Time-bound (session, one-time, or persistent)
- User-revocable at any time

## License

MIT