@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

npm install @ident-agency/agent

Integration with Core

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:

// 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:

// 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