logpose

# logpose

Verifiable reputation SDK for AI agents. Agents cryptographically sign W3C Verifiable Credentials proving what they've done, and anyone can verify offline.

## What It Is

Logpose is a TypeScript SDK that lets AI agents cryptographically prove what they've done. An agent signs a W3C Verifiable Credential 2.0 attesting to a task it completed, and anyone can verify that credential offline — no server, no database, no trust in a third party.

A2A (Google's Agent-to-Agent protocol) tells agents how to talk. Logpose tells them who to trust.

## Packages

| Package | Description |
|---------|-------------|
| @logpose-dev/logpose | Core SDK — credential creation, signing, verification |
| @logpose-dev/a2a | A2A transport layer — agent card reputation, middleware, evaluation |

## Install

```bash
pnpm add @logpose-dev/logpose
# A2A transport layer (optional)
pnpm add @logpose-dev/a2a
```

## How It Works

Each agent gets an Ed25519 keypair encoded as a did:key identity. When it completes a task, it creates a JSON credential containing the task details, canonicalizes it with RFC 8785 JCS, signs the bytes, and attaches the signature as a proof. Verification reverses this: strip the proof, re-canonicalize, check the Ed25519 signature against the issuer's public key extracted from the DID.

## Core API

```typescript
import { createAttestor, verifyCredential } from '@logpose-dev/logpose';

// Create an attestor (generates Ed25519 keypair)
const agent = await createAttestor();
console.log(agent.did); // did:key:z6Mk...

// Record a credential
const credential = await agent.record({
  task: 'code-review',
  outcome: 'approved',
  evidence: { pr: 42, repo: 'acme/api' },
});

// Verify it — no network call, no database lookup
const result = await verifyCredential(credential);
// { valid: true, issuerTrusted: true, expired: false, revoked: false }
```

### Cross-Agent Attestation

```typescript
import { createAttestor, createHolderBinding } from '@logpose-dev/logpose';

const agentA = await createAttestor();
const agentB = await createAttestor();

// Agent A attests about Agent B (with B's consent)
const binding = createHolderBinding(/* B's keypair */, 'consent-nonce');
const crossAttestation = await agentA.record(
  { task: 'peer-review', outcome: 'passed' },
  { subject: agentB.did, holderBinding: binding },
);
```

## A2A Transport Layer

```typescript
import { advertise, serve, evaluate } from '@logpose-dev/a2a';

// Generate reputation block for A2A Agent Cards
const reputationBlock = advertise(attestor);

// Serve credentials at /.well-known/logpose.json
app.use(serve(attestor));

// Evaluate another agent's credentials before delegating
const report = await evaluate('https://other-agent.example.com');
```

## Design Decisions

| Decision | Alternative | Why |
|----------|-------------|-----|
| W3C VC 2.0 | Custom format | Credentials are signed documents in the wild — can't migrate later |
| RFC 8785 JCS | Hand-rolled sorted keys | Handles Unicode normalization, number formatting edge cases |
| did:key | did:pkh, did:web | Self-describing, no registration needed |
| @noble/curves | Node crypto, libsodium | Pure JS, zero native deps, audited, works in browsers/edge/CI |
| Injectable trust registry | Global mutable state | verifyCredential(cred, { trustedIssuers }) — no shared state |

## Ecosystem

Logpose is positioned as the trust layer for Google's A2A protocol ecosystem (150+ organizations, Linux Foundation governance). A2A handles agent discovery and communication — Agent Cards, JSON-RPC, SSE, gRPC — but does not solve trust. Agent Cards are self-reported capabilities with no verification.

Logpose provides the missing piece: cryptographic proof that an agent has actually delivered on its claimed capabilities.

## CTEF Standard

The Composable Trust Evidence Format (CTEF) is a multi-provider attestation envelope format developed across the A2A community (RFC #1734). It defines 9+ provider categories for different types of trust evidence.

**Logpose is the named reference implementation for the `peer_review` category** — the only category that captures direct agent-to-agent performance attestation.

Other provider categories in the standard include static analysis, behavioral monitoring, continuous monitoring, compliance risk, transactional evidence, sovereignty verification, and identity.

The vocabulary registry for the standard is maintained at [aeoess/agent-governance-vocabulary](https://github.com/aeoess/agent-governance-vocabulary). The maintainer ([aeoess](https://github.com/aeoess)) is also affiliated with Anthropic.

## Contributions

### Vocabulary Standard (agent-governance-vocabulary)
- Added `peer_review` signal type to the canonical vocabulary
- Created crosswalk mapping logpose credential fields to the vocabulary schema
- A second, independent `peer_review` crosswalk was subsequently opened by another contributor — two implementations meeting the threshold for the signal type to land as canonical

### CTEF RFC (Composable Trust Evidence Format)
- Added `aud` (audience) claim to the envelope specification (Section 4.2 Optional Fields)
- Added verification step for `aud` checking (Section 9.1)
- `aud` complements existing `jti` replay prevention: `jti` prevents the same attestation consumed twice by the same gateway; `aud` prevents an attestation intended for Gateway A from being accepted by Gateway B
- The RFC author confirmed `aud` will be included in the v0.2 revision

### A2A Protocol Discussions
- Published RFC for "Verifiable Reputation Extension for Agent Cards" (Discussion #1740)
- Proposed `.well-known/trust-evidence.json` pointer pattern — Agent Card stays light, evidence fetched on demand
- Referenced by other contributors as the transport layer complement to CTEF

### CTEF Envelope Mapping
- Published full JSON mapping of logpose credentials into the RFC Section 4 envelope format
- Field-by-field mapping table with rationale for confidence scoring