@smartledger/envelope 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Gregory Ward (aka Codenlighten)
+Founder: Codenlighten.org
+Co-founder & Chief Technology Officer: SmartLedger.Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,452 @@
+# @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.**

package/dist/cjs/envelope.d.ts

@@ -0,0 +1,70 @@
+import type { KeySDK } from '@smartledger/keys';
+import type { SignedEnvelope, CreateEnvelopeOptions, VerifyEnvelopeOptions, VerificationResult, EnvelopeMetadata } from './types.js';
+/**
+ * Create a signed envelope from payload
+ *
+ * @example
+ * ```typescript
+ * import { createKeySDK } from '@smartledger/keys';
+ * import { createSignedEnvelope } from '@smartledger/envelope';
+ *
+ * const sdk = createKeySDK();
+ * const key = await sdk.createKey('my-agent', { primarySignatureSuite: 'ml-dsa-87' });
+ *
+ * const envelope = await createSignedEnvelope(
+ *   sdk,
+ *   key.meta.keyId,
+ *   { message: "Hello, world!" },
+ *   { creator: 'my-agent', contentType: 'greeting' }
+ * );
+ * ```
+ */
+export declare function createSignedEnvelope<T>(sdk: KeySDK, keyId: string, payload: T, options: CreateEnvelopeOptions): Promise<SignedEnvelope<T>>;
+/**
+ * Verify a signed envelope
+ *
+ * @example
+ * ```typescript
+ * const result = await verifySignedEnvelope(sdk, envelope);
+ * if (result.valid) {
+ *   console.log('Verified! Created by:', result.creator);
+ *   console.log('Payload:', envelope.payload);
+ * }
+ * ```
+ */
+export declare function verifySignedEnvelope<T>(sdk: KeySDK, envelope: SignedEnvelope<T>, options?: VerifyEnvelopeOptions): Promise<VerificationResult>;
+/**
+ * Extract payload from envelope without verification
+ * Use only when verification was done previously
+ */
+export declare function extractPayload<T>(envelope: SignedEnvelope<T>): T;
+/**
+ * Get envelope metadata
+ */
+export declare function getEnvelopeMeta<T>(envelope: SignedEnvelope<T>): EnvelopeMetadata;
+/**
+ * Check if envelope has PQ signature
+ */
+export declare function hasPQSignature<T>(envelope: SignedEnvelope<T>): boolean;
+/**
+ * Check if envelope has on-chain anchor
+ */
+export declare function hasAnchor<T>(envelope: SignedEnvelope<T>): boolean;
+/**
+ * Create a chain of custody by linking envelopes
+ *
+ * @example
+ * ```typescript
+ * const original = await createSignedEnvelope(sdk, keyId, data, { creator: 'alice' });
+ * const updated = await createEnvelopeChain(
+ *   sdk,
+ *   keyId,
+ *   updatedData,
+ *   original,
+ *   { creator: 'bob', contentType: 'revision' }
+ * );
+ * // updated.meta.parentId === hash(original)
+ * ```
+ */
+export declare function createEnvelopeChain<T>(sdk: KeySDK, keyId: string, payload: T, parentEnvelope: SignedEnvelope<any>, options: Omit<CreateEnvelopeOptions, 'parentId'>): Promise<SignedEnvelope<T>>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/cjs/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAmD5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,CAEhE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAEhF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAEtE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,cAAc,CAAC,GAAG,CAAC,EACnC,OAAO,EAAE,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,GAC/C,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAW5B"}