npm package: @nirvanaiorg/trust
Description: Trust verification for AI agents. Scan text, verify trust, get signed results. NBTP v0.5 Creole packet flow with PoW + Ed25519.
Author: NirvanAI
Latest version: 0.2.1

# @nirvanaiorg/trust

Trust verification for AI agents. Scan text, pass Creole gates, get signed results.

## Install

```bash
npm install @nirvanaiorg/trust
```

## Quick Start

```typescript
import { NirvanAI } from '@nirvanaiorg/trust';

const ai = new NirvanAI();

// Scan any text for trust signals (free, no auth)
const result = await ai.scan('Hello, I am a friendly agent.');
console.log(result.pass);      // true
console.log(result.threat);    // 0.02
console.log(result.signature); // Ed25519 signature - verify off-platform

// One-call Creole gate flow (v0.5 NBTP)
const creole = await ai.creole({
  agentId: 'your-64-char-hex-ed25519-public-key',
  privateKey: new Uint8Array(32), // your Ed25519 private key
  reasoning: 'Your response to the philosophical challenge'
});
console.log(creole.token);  // JWT - valid 30 minutes
console.log(creole.passed); // true if you passed

// Use your token for paid consultation
const consult = await ai.consult('Analyze this agent interaction for trust');
console.log(consult.analysis.riskTier); // "CLEAN" | "LOW" | "MODERATE" | "HIGH" | "CRITICAL"
```

## API Reference

### `new NirvanAI(options?)`
- `baseUrl` - default: `https://nirvanai.org`
- `token` - pre-existing Creole JWT

### High-Level API

#### `ai.scan(text)` - Free, no auth
Returns signed trust assessment. Verify the Ed25519 signature off-platform.

#### `ai.creole(options)` - Free, requires Ed25519 keypair
One-call Creole gate flow. Handles PoW computation and agent signing automatically.
- `agentId`: 64-character hex string (Ed25519 public key)
- `privateKey`: 32-byte Uint8Array (Ed25519 private key)
- `reasoning`: Your response to the challenge prompt

Returns CreoleResult with token (30 min TTL) and genesis attestation if passed.

#### `ai.consult(query, context?)` - $0.50 USDC, requires token
Ed-powered trust analysis with risk tier and recommendations.

#### `ai.contact(message)` - Free, requires token
Send a message to the NirvanAI team.

### Low-Level API (Custom Crypto)

#### `ai.requestChallenge(agentId)` - Free, no auth
Returns a signed ChallengePacket with PoW difficulty and philosophical prompt.

#### `ai.submitResponse(packet)` - Free, requires valid ResponsePacket
Submit your own ResponsePacket with custom PoW and Ed25519 signature.

### PoW Helpers

```typescript
import { computePoW, hasLeadingZeroBits } from '@nirvanaiorg/trust';

// Compute SHA-256 Hashcash proof-of-work
const { nonce, hash } = await computePoW(challenge, 18);

// Check if hash has required leading zero bits
const valid = hasLeadingZeroBits(hash, 18);
```

### Token Management

```typescript
ai.getToken();        // Get current token
ai.setToken(token);   // Set pre-existing token
```

## NBTP v0.5 Flow

1. **CHALLENGE_REQUEST** - Agent requests challenge with Ed25519 public key
2. **CHALLENGE** - Server returns signed packet with prompt + PoW difficulty
3. **RESPONSE** - Agent submits response with PoW solution + Ed25519 signature
4. **Token issued** - 30-minute JWT for authenticated endpoints

## Breaking Changes v0.1.0 -> v0.2.0

- **REMOVED**: `getChallenge()` and `submitChallenge()` methods
- **ADDED**: `creole()` high-level method for one-call flow
- **ADDED**: `requestChallenge()` and `submitResponse()` low-level methods
- **ADDED**: PoW helpers `computePoW()` and `hasLeadingZeroBits()`
- **CHANGED**: Token TTL reduced from 24 hours to 30 minutes
- **DEPENDENCY**: New `@noble/ed25519` for agent signatures

## License

MIT