Audit

Log agent actions and query the tamper-evident audit trail.

Overview

The audit sub-client provides a tamper-evident, append-only audit trail for all agent actions. Each entry is hash-chained to the previous entry, providing cryptographic integrity guarantees.

await grantex.audit.log({
  agentId: agent.id,
  agentDid: agent.did,
  grantId: token.grantId,
  principalId: 'user_123',
  action: 'email.sent',
  status: 'success',
  metadata: { to: '[e-mail]', subject: 'Flight confirmation' },
});

---

audit.log()

Log an agent action to the audit trail.

const entry = await grantex.audit.log({
  agentId: 'ag_01HXYZ...',
  agentDid: 'did:grantex:ag_01HXYZ...',
  grantId: 'grnt_01HXYZ...',
  principalId: 'user_123',
  action: 'payment.initiated',
  status: 'success',
  metadata: { amount: 420, currency: 'USD', merchant: 'Air India' },
});

console.log(entry.entryId);   // 'alog_01HXYZ...'
console.log(entry.hash);      // SHA-256 hash of this entry
console.log(entry.prevHash);  // Hash of the previous entry (null for the first)
console.log(entry.timestamp); // '2026-02-28T12:00:00Z'

Parameters

agentId · string · required

The agent that performed the action.

agentDid · string · required

The decentralized identifier of the agent that performed the action.

grantId · string · required

The grant under which the action was performed.

principalId · string · required

The principal on whose behalf the action was performed.

action · string · required

A descriptive action identifier (e.g. 'email.sent', 'payment.initiated', 'file.uploaded').

metadata · Record<string, unknown>

Arbitrary metadata to attach to the audit entry.

status · string

Action outcome: 'success', 'failure', or 'blocked'.

Response: AuditEntry

entryId · string

Unique audit entry identifier.

agentId · string

The agent that performed the action.

agentDid · string

The agent’s decentralized identifier.

grantId · string

The associated grant ID.

principalId · string

The user who authorized the grant.

action · string

The action identifier.

metadata · Record<string, unknown>

Arbitrary metadata attached to the entry.

hash · string

SHA-256 hash of this entry, used for chain integrity verification.

prevHash · string | null

Hash of the previous entry in the chain. null for the first entry.

timestamp · string

ISO 8601 timestamp when the action was logged.

status · string

Action outcome: 'success', 'failure', or 'blocked'.

---

audit.list()

Query audit entries with optional filters.

const result = await grantex.audit.list({
  agentId: 'ag_01HXYZ...',
  action: 'payment.initiated',
  since: '2026-02-01T00:00:00Z',
  until: '2026-02-28T23:59:59Z',
  page: 1,
  pageSize: 50,
});

console.log(result.entries.length);  // entries returned on this page
for (const entry of result.entries) {
  console.log(`[${entry.timestamp}] ${entry.action} - ${entry.status}`);
}

Parameters

agentId · string

Filter by agent ID.

grantId · string

Filter by grant ID.

principalId · string

Filter by principal (user) ID.

action · string

Filter by action identifier.

since · string

ISO 8601 start date for the query range.

until · string

ISO 8601 end date for the query range.

page · number

Page number (1-indexed).

pageSize · number

Number of entries per page.

Response: ListAuditResponse

entries · AuditEntry[]

Array of audit entry objects.

total · number

Total number of entries matching the filters.

page · number

Current page number.

pageSize · number

Number of entries per page.

---

audit.get()

Retrieve a single audit entry by its ID.

const entry = await grantex.audit.get('alog_01HXYZ...');

console.log(entry.action);   // 'payment.initiated'
console.log(entry.hash);     // 'a1b2c3d4e5f6...'
console.log(entry.prevHash); // '9z8y7x6w5v4u...'
console.log(entry.metadata); // { amount: 420, currency: 'USD' }

Parameters

entryId · string · required

The audit entry ID to retrieve.

Response

Returns an AuditEntry object.

Chain integrity

Each audit entry contains a hash of its contents and a prevHash linking it to the previous entry. This creates a tamper-evident chain similar to a blockchain. If any entry is modified after the fact, the hash chain breaks.

Use the Compliance evidence pack to verify chain integrity programmatically:

const pack = await grantex.compliance.evidencePack({ framework: 'soc2' });
console.log(pack.chainIntegrity.valid);          // true
console.log(pack.chainIntegrity.checkedEntries);  // 1024