npm package: @smartledger/envelope
Description: Canonical SignedResponse/SignedEnvelope schema for verifiable AI outputs and content provenance
Author: Gregory Ward
Latest version: 1.0.0

# @smartledger/envelope

**Simple, verifiable content signing for any application.**

A lightweight signing primitive that wraps content with cryptographic proof. Use it to build verifiable AI responses, signed documents, authenticated API calls, or audit trails.

---

## Quick Start

```typescript
import { createAppIdentity } from '@smartledger/envelope';

// Create an identity (in-memory keys)
const identity = await createAppIdentity({ name: 'MyCoolApp' });

// Sign anything
const signed = await identity.signJson({ message: "Hello, world!" });

// Verify anything  
const result = await identity.verifyJson(signed);
console.log('Valid:', result.valid); // true
```

**Keys are ephemeral (in-memory) by default.** For persistence, see [Storage Examples](#storage-examples) below.

---

## What It Does

This package provides:

1. **SignedEnvelope format** - A standard schema for signed content
2. **Simple API** - One-line setup, easy signing/verification
3. **Post-quantum support** - ML-DSA-87 (NIST FIPS 204) by default
4. **Flexible** - Works with any JSON-serializable data

### What It Doesn't Do

This is a **primitive**, not a complete application. It doesn't include:

- ❌ Persistent key storage (but see [examples](#storage-examples) for how to add it)
- ❌ DID generation or resolution
- ❌ Verifiable Credentials
- ❌ Blockchain integration
- ❌ KYC or identity verification

Those features belong in your application or separate packages. This library gives you the cryptographic foundation to build them.

---

## Use Cases

### Verifiable AI Responses

```typescript
import OpenAI from 'openai';

const identity = await createAppIdentity({ name: 'MyAI' });
const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain quantum computing' }]
});

// Sign the AI response
const signed = await identity.signJson(response, {
  contentType: 'ai-response'
});

// Now you have cryptographic proof of what your AI said and when
```

### Signed Content / Blog Posts

```typescript
const identity = await createAppIdentity({ name: 'MyBlog' });

const post = {
  title: "Why Cryptography Matters",
  content: "...",
  author: "Alice",
};

const signedPost = await identity.signJson(post, {
  contentType: 'blog-post'
});

// Readers can verify authenticity
// Authors can't deny writing it
// Editors can't change it without detection
```

### Microservice Authentication

```typescript
// Service A signs requests
const serviceA = await createAppIdentity({ name: 'ServiceA' });
const request = await serviceA.signJson({
  action: 'process-payment',
  amount: 100,
});

// Service B verifies before processing
const result = await serviceB.verifyJson(request);
if (result.valid && result.creator === 'ServiceA') {
  // Process - we know it's really from ServiceA
}
```

### Audit Trails with Chain of Custody

```typescript
import { createEnvelopeChain } from '@smartledger/envelope';

const original = await identity.signJson(
  { status: 'draft', content: '...' }
);

// Link revision to original
const revision = await createEnvelopeChain(
  identity.getSDK(),
  identity.keyId,
  { status: 'reviewed', content: '...' },
  original,
  { creator: 'reviewer' }
);

// revision.meta.parentId === hash(original)
// Full provenance chain preserved
```

---

## Features

### 🔐 Post-Quantum Ready

Uses ML-DSA-87 (NIST FIPS 204) by default - quantum-resistant signatures:

```typescript
const identity = await createAppIdentity({
  name: 'MyApp',
  algorithm: 'ml-dsa-87'  // Default
});
```

Or use ECDSA for Bitcoin compatibility:

```typescript
const identity = await createAppIdentity({
  name: 'MyApp',
  algorithm: 'bsv-ecdsa-secp256k1'
});
```

### 📜 Chain of Custody

Link envelopes to create verifiable revision chains:

```typescript
const updated = await createEnvelopeChain(
  sdk, keyId, updatedData, originalEnvelope,
  { creator: 'editor' }
);
// updated.meta.parentId === hash(originalEnvelope)
```

### 🔗 Extensible Metadata

Add custom metadata for your use case:

```typescript
const signed = await createSignedEnvelope(sdk, keyId, data, {
  creator: 'MyApp',
  contentType: 'invoice',
  metadata: {
    invoiceNumber: 'INV-001',
    customField: 'anything'
  }
});
```

---

## Envelope Format

The `SignedEnvelope` is a simple, universal format:

```typescript
interface SignedEnvelope<T> {
  payload: T;              // Your actual data
  
  meta: {
    version: string;       // Schema version
    creator: string;       // Who created it
    createdAt: string;     // ISO 8601 timestamp
    contentType?: string;  // Optional type hint
    parentId?: string;     // Optional parent hash
    // ... custom fields
  };
  
  _signature: {
    algorithm: string;     // e.g., 'ml-dsa-87'
    keyId: string;         // Key identifier
    publicKey: string;     // Base64 public key (embedded for verification)
    signature: string;     // Base64 signature
    timestamp: string;     // When signed
  };
}
```

This format can be:
- Stored in databases (MongoDB, Postgres, etc.)
- Sent over HTTP/WebSocket
- Saved to files
- Verified years later

---

## Installation

```bash
npm install @smartledger/envelope
```

Requires:
- `@smartledger/keys` (automatically installed)
- `@smartledger/crypto` (automatically installed)

---

## Storage Examples

### In-Memory (Default)

Keys are ephemeral - perfect for testing or short-lived processes:

```typescript
const identity = await createAppIdentity({ name: 'TestApp' });
// Keys lost when process exits
```

### File-Based Storage

Implement your own `KeyStorage` class (see `@smartledger/crypto` for interface):

```typescript
import { createKeySDK } from '@smartledger/keys';
import { KeyRegistry } from '@smartledger/crypto';
import { FileKeyStorage } from './storage'; // Your implementation

const sdk = createKeySDK({
  keyRegistry: new KeyRegistry(new FileKeyStorage('./keys'))
});

const identity = await createAppIdentity({
  name: 'MyApp',
  sdk  // Use your SDK with persistence
});
```

See `/examples/file-storage/` for a complete implementation.

### Database Storage

Similar pattern - implement `KeyStorage` for your database:

```typescript
import { MongoKeyStorage } from './storage'; // Your implementation

const sdk = createKeySDK({
  keyRegistry: new KeyRegistry(new MongoKeyStorage(mongoClient))
});

const identity = await createAppIdentity({ name: 'MyApp', sdk });
```

See `/examples/mongodb-storage/` for a complete implementation.

---

## API Reference

### High-Level API (Recommended)

#### `createAppIdentity(options)`

Create a signing identity:

```typescript
const identity = await createAppIdentity({
  name: 'MyApp',             // Required: app/agent name
  algorithm: 'ml-dsa-87',    // Optional: 'ml-dsa-87' | 'bsv-ecdsa-secp256k1'
  sdk: customSDK,            // Optional: provide your own SDK with custom storage
  existingKeyId: 'key-123'   // Optional: use existing key
});
```

#### `signJson(appName, data, options?)`

Convenience function for one-shot signing:

```typescript
const signed = await signJson('MyApp', { message: "Hello!" });
```

**Note:** Uses a global SDK instance. Keys persist across calls within the same process but are lost when the process exits.

#### `verifyJson(envelope)`

Convenience function for one-shot verification:

```typescript
const result = await verifyJson(receivedEnvelope);
```

Verifies envelopes created with `signJson()` in the same process.

### Low-Level API (Advanced)

#### `createSignedEnvelope(sdk, keyId, payload, options)`

Full control over envelope creation:

```typescript
import { createKeySDK } from '@smartledger/keys';
import { createSignedEnvelope } from '@smartledger/envelope';

const sdk = createKeySDK();
const key = await sdk.createKey('agent', { primarySignatureSuite: 'ml-dsa-87' });

const envelope = await createSignedEnvelope(sdk, key.meta.keyId, data, {
  creator: 'my-agent',
  contentType: 'custom-type',
  metadata: { custom: 'fields' },
  anchor: { chain: 'bitcoin', txId: '0x...', timestamp: '...' }
});
```

#### `verifySignedEnvelope(sdk, envelope, options?)`

Full control over verification:

```typescript
const result = await verifySignedEnvelope(sdk, envelope, {
  maxAge: 86400000,         // Reject if older than 24h
  expectedCreator: 'alice', // Reject if not from alice
});
```

#### Utility Functions

```typescript
import {
  extractPayload,
  getEnvelopeMeta,
  hasPQSignature,
  hasAnchor,
  createEnvelopeChain
} from '@smartledger/envelope';

// Extract payload without verification (use with caution)
const data = extractPayload(envelope);

// Get metadata
const meta = getEnvelopeMeta(envelope);

// Check capabilities
const hasPQ = hasPQSignature(envelope);      // false (not implemented yet)
const hasChain = hasAnchor(envelope);         // true if anchor present

// Create linked envelope
const child = await createEnvelopeChain(sdk, keyId, data, parent, options);
```

---

## Philosophy

Digital content should answer four questions:

1. **WHO** - Cryptographically proven creator
2. **WHAT** - Content hash for tamper detection
3. **WHEN** - Timestamp (ISO 8601)
4. **HOW** - Algorithm + public key for verification

This envelope format provides all four. The format is simple and can be verified years later.

---

## Testing

```bash
cd packages/envelope
npm test
```

78 tests covering:
- Envelope creation and verification
- Helper functions
- Type definitions
- Real-world scenarios (AI, blogs, microservices)
- Chain of custody
- Tampering detection

---

## Roadmap

### Current (v1.0.0)
- ✅ SignedEnvelope format
- ✅ ML-DSA-87 and ECDSA support
- ✅ Chain of custody
- ✅ Simple API
- ✅ 78 comprehensive tests

### Future
- [ ] Embedded public key verification (verify without SDK)
- [ ] JWS/JWT compatibility layer
- [ ] DID document generation
- [ ] Dual-signing (ECDSA + ML-DSA)
- [ ] On-chain anchor verification
- [ ] Browser bundle

---

## License

MIT - See [LICENSE](../../LICENSE)

---

## Author

**Gregory Ward (Codenlighten)**  
Founder: [Codenlighten.org](https://codenlighten.org)  
Co-founder & CTO: [SmartLedger.Technology](https://smartledger.technology)

---

## Related Packages

- [@smartledger/keys](../keys/) - Key management SDK
- [@smartledger/crypto](../crypto/) - Low-level cryptography primitives

---

**Status:** 🚧 Alpha - API Stable, Features Complete, Tests Pending

**The cryptographic nervous system for verifiable AI.**