@coolwithakay/uatp 0.1.0

package/README.md

@@ -0,0 +1,236 @@
+# UATP TypeScript SDK
+
+Cryptographic audit trails for AI decisions.
+
+[![npm](https://img.shields.io/npm/v/uatp)](https://www.npmjs.com/package/uatp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install @coolwithakay/uatp
+```
+
+## Quick Start
+
+```typescript
+import { UATP } from '@coolwithakay/uatp';
+
+const client = new UATP();
+
+// Create and sign a capsule (keys generated locally, never transmitted)
+const result = await client.certify({
+  task: 'Loan decision',
+  decision: 'Approved for $50,000 at 5.2% APR',
+  reasoning: [
+    { step: 1, thought: 'Credit score 720 (excellent)', confidence: 0.95 },
+    { step: 2, thought: 'Debt-to-income 0.28 (acceptable)', confidence: 0.90 }
+  ]
+});
+
+console.log(result.capsuleId);   // cap_xyz123...
+console.log(result.signature);   // Ed25519 signature
+console.log(result.publicKey);   // Your verification key
+```
+
+## Zero-Trust Architecture
+
+Your private key **never leaves your device**:
+
+```
+┌─────────────────────────────┐
+│  YOUR DEVICE                │
+│  ✓ Private key (derived)    │
+│  ✓ ALL signing happens here │
+│  ✓ Ed25519 + PBKDF2 480K    │
+└──────────────┬──────────────┘
+               │ Only hash sent
+               ▼
+┌─────────────────────────────┐
+│  UATP SERVER (optional)     │
+│  - Timestamp service        │
+│  - Capsule storage          │
+└─────────────────────────────┘
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { UATP } from '@coolwithakay/uatp';
+
+const client = new UATP();
+
+const result = await client.certify({
+  task: 'Product recommendation',
+  decision: 'Recommended iPhone 15 Pro',
+  reasoning: [
+    { step: 1, thought: 'User prefers Apple ecosystem', confidence: 0.92 },
+    { step: 2, thought: 'Budget matches Pro pricing', confidence: 0.88 }
+  ]
+});
+```
+
+### With Custom Passphrase (Production)
+
+```typescript
+const result = await client.certify({
+  task: 'Medical diagnosis',
+  decision: 'Recommend follow-up tests',
+  reasoning: [
+    { step: 1, thought: 'Symptoms consistent with condition X', confidence: 0.85 }
+  ],
+  passphrase: 'your-secure-passphrase',
+  deviceBound: false
+});
+```
+
+### Verify Locally (No Server Needed)
+
+```typescript
+const verification = client.verifyLocal(capsule);
+
+if (verification.valid) {
+  console.log('Capsule is authentic!');
+} else {
+  console.log('Verification failed:', verification.errors);
+}
+```
+
+### Store on Server
+
+```typescript
+const result = await client.certify({
+  task: 'Insurance claim',
+  decision: 'Approved: $5,000',
+  reasoning: [...],
+  storeOnServer: true
+});
+
+console.log(result.proofUrl); // https://...
+```
+
+### Retrieve Proof
+
+```typescript
+const proof = await client.getProof('cap_abc123');
+console.log(proof.payload.task);
+console.log(proof.payload.decision);
+```
+
+## API Reference
+
+### `new UATP(config?)`
+
+Create a new UATP client.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | - | API key for authenticated requests |
+| `baseUrl` | `string` | `http://localhost:8000` | UATP server URL |
+| `timeout` | `number` | `30000` | Request timeout (ms) |
+
+### `client.certify(options)`
+
+Create a signed capsule.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `task` | `string` | Yes | Description of the task |
+| `decision` | `string` | Yes | The AI's decision |
+| `reasoning` | `ReasoningStep[]` | Yes | Reasoning steps |
+| `passphrase` | `string` | No | Key encryption passphrase |
+| `deviceBound` | `boolean` | No | Derive passphrase from device (default: true) |
+| `confidence` | `number` | No | Overall confidence (0-1) |
+| `metadata` | `object` | No | Additional metadata |
+| `requestTimestamp` | `boolean` | No | Get RFC 3161 timestamp (default: true) |
+| `storeOnServer` | `boolean` | No | Store on UATP server (default: false) |
+
+### `client.verifyLocal(capsule)`
+
+Verify a capsule cryptographically without server.
+
+### `client.getProof(capsuleId)`
+
+Retrieve proof from server.
+
+### `client.listCapsules(limit?)`
+
+List capsules from server.
+
+### `client.recordOutcome(capsuleId, outcome)`
+
+Record actual outcome for a decision.
+
+## Framework Integration
+
+### React
+
+```typescript
+import { UATP } from '@coolwithakay/uatp';
+import { useState } from 'react';
+
+function useUATP() {
+  const [client] = useState(() => new UATP());
+
+  const certify = async (task: string, decision: string, reasoning: any[]) => {
+    return client.certify({ task, decision, reasoning });
+  };
+
+  return { certify };
+}
+```
+
+### Next.js API Route
+
+```typescript
+// pages/api/certify.ts
+import { UATP } from '@coolwithakay/uatp';
+
+const client = new UATP({ baseUrl: process.env.UATP_URL });
+
+export default async function handler(req, res) {
+  const result = await client.certify(req.body);
+  res.json({ capsuleId: result.capsuleId });
+}
+```
+
+### Lovable / AI App Builders
+
+```typescript
+// In your Lovable-generated app
+import { UATP } from '@coolwithakay/uatp';
+
+const client = new UATP();
+
+// Audit every AI decision
+async function makeDecision(userQuery: string) {
+  const aiResponse = await callYourAI(userQuery);
+
+  // Create audit trail
+  const proof = await client.certify({
+    task: userQuery,
+    decision: aiResponse.decision,
+    reasoning: aiResponse.steps.map((s, i) => ({
+      step: i + 1,
+      thought: s.thought,
+      confidence: s.confidence
+    }))
+  });
+
+  return { ...aiResponse, proofId: proof.capsuleId };
+}
+```
+
+## Security
+
+- **Ed25519** signatures (128-bit security)
+- **PBKDF2-HMAC-SHA256** key derivation (480,000 iterations)
+- **SHA-256** content hashing
+- Keys derived from passphrase, never stored in plaintext
+- Optional **RFC 3161** timestamps from external authority
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,268 @@
+export { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+
+/**
+ * UATP TypeScript SDK - Type Definitions
+ */
+interface ReasoningStep {
+    step: number;
+    thought: string;
+    confidence: number;
+    action?: string;
+    data_sources?: DataSource[];
+    reasoning?: string;
+    plain_language?: string;
+}
+interface DataSource {
+    source: string;
+    value: unknown;
+    timestamp?: string;
+    api_endpoint?: string;
+}
+interface CertifyOptions {
+    /** Description of the task */
+    task: string;
+    /** The AI's final decision */
+    decision: string;
+    /** List of reasoning steps */
+    reasoning: ReasoningStep[];
+    /** Optional passphrase for key encryption (recommended for production) */
+    passphrase?: string;
+    /** If true, derive passphrase from browser/device info (default: true) */
+    deviceBound?: boolean;
+    /** Overall confidence score (0-1). Auto-calculated if not provided */
+    confidence?: number;
+    /** Additional metadata to attach */
+    metadata?: Record<string, unknown>;
+    /** Request RFC 3161 timestamp from server (default: true) */
+    requestTimestamp?: boolean;
+    /** Store capsule on UATP server (default: false) */
+    storeOnServer?: boolean;
+}
+interface SignedCapsule {
+    /** Unique capsule identifier */
+    capsuleId: string;
+    /** Ed25519 signature (hex) */
+    signature: string;
+    /** Public key for verification (hex) */
+    publicKey: string;
+    /** SHA-256 hash of content (hex) */
+    contentHash: string;
+    /** ISO timestamp of signing */
+    timestamp: string;
+    /** Original content that was signed */
+    content: CapsuleContent;
+    /** RFC 3161 timestamp token (if requested) */
+    timestampToken?: string;
+    /** Timestamp authority used */
+    timestampTsa?: string;
+    /** Whether stored on server */
+    serverStored?: boolean;
+    /** URL to verify on server */
+    proofUrl?: string;
+}
+interface CapsuleContent {
+    task: string;
+    decision: string;
+    reasoning_chain: ReasoningStep[];
+    confidence: number;
+    metadata: Record<string, unknown>;
+}
+interface CapsuleProof {
+    capsuleId: string;
+    capsuleType: string;
+    status: string;
+    timestamp: Date;
+    payload: Record<string, unknown>;
+    rawData: Record<string, unknown>;
+}
+interface VerificationResult {
+    valid: boolean;
+    signatureValid: boolean;
+    hashValid: boolean;
+    timestampValid?: boolean;
+    errors?: string[];
+}
+interface UATPConfig {
+    /** API key for authenticated requests */
+    apiKey?: string;
+    /** Base URL of UATP server (default: http://localhost:8000) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface KeyPair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+
+/**
+ * UATP TypeScript SDK - Client
+ *
+ * Zero-Trust Architecture:
+ * - Private keys NEVER leave your device
+ * - All signing happens locally using Ed25519
+ * - Only content hash sent to server for RFC 3161 timestamping
+ * - Capsules can be verified independently without UATP
+ */
+
+declare class UATP {
+    private apiKey?;
+    private baseUrl;
+    private timeout;
+    /**
+     * Initialize UATP client.
+     *
+     * @example
+     * ```typescript
+     * // Local development
+     * const client = new UATP();
+     *
+     * // Production
+     * const client = new UATP({
+     *   apiKey: 'your-api-key',
+     *   baseUrl: 'https://api.uatp.io'
+     * });
+     * ```
+     */
+    constructor(config?: UATPConfig);
+    /**
+     * Create a cryptographically certified capsule for an AI decision.
+     *
+     * ZERO-TRUST: Private key NEVER leaves your device.
+     * - All signing happens locally using Ed25519
+     * - Only the content hash is sent to UATP for timestamping
+     * - Capsules can be verified independently without UATP
+     *
+     * @example
+     * ```typescript
+     * const result = await client.certify({
+     *   task: 'Loan decision',
+     *   decision: 'Approved for $50,000 at 5.2% APR',
+     *   reasoning: [
+     *     { step: 1, thought: 'Credit score 720 (excellent)', confidence: 0.95 },
+     *     { step: 2, thought: 'Debt-to-income 0.28 (acceptable)', confidence: 0.90 }
+     *   ]
+     * });
+     *
+     * console.log(result.capsuleId);
+     * console.log(result.signature);
+     * ```
+     */
+    certify(options: CertifyOptions): Promise<SignedCapsule>;
+    /**
+     * Retrieve full cryptographic proof for a capsule.
+     *
+     * @example
+     * ```typescript
+     * const proof = await client.getProof('cap_abc123');
+     * console.log(proof.payload.task);
+     * ```
+     */
+    getProof(capsuleId: string): Promise<CapsuleProof>;
+    /**
+     * List capsules from the server.
+     *
+     * @example
+     * ```typescript
+     * const capsules = await client.listCapsules(10);
+     * for (const cap of capsules) {
+     *   console.log(cap.capsuleId, cap.status);
+     * }
+     * ```
+     */
+    listCapsules(limit?: number): Promise<CapsuleProof[]>;
+    /**
+     * Verify a capsule locally without server.
+     *
+     * This can be done by anyone - no UATP infrastructure required.
+     * Only uses cryptographic data embedded in the capsule.
+     *
+     * @example
+     * ```typescript
+     * const result = client.verifyLocal(capsule);
+     * if (result.valid) {
+     *   console.log('Capsule is authentic!');
+     * }
+     * ```
+     */
+    verifyLocal(capsule: SignedCapsule): VerificationResult;
+    /**
+     * Record the actual outcome of an AI decision (ground truth).
+     *
+     * @example
+     * ```typescript
+     * await client.recordOutcome('cap_abc123', {
+     *   result: 'successful',
+     *   aiWasCorrect: true,
+     *   financialImpact: 2500,
+     *   notes: 'Loan fully paid on time'
+     * });
+     * ```
+     */
+    recordOutcome(capsuleId: string, outcome: {
+        result?: string;
+        aiWasCorrect?: boolean;
+        financialImpact?: number;
+        customerSatisfaction?: number;
+        notes?: string;
+    }): Promise<boolean>;
+    /**
+     * Internal fetch wrapper with timeout and headers.
+     */
+    private fetch;
+}
+
+/**
+ * UATP TypeScript SDK - Cryptographic Operations
+ *
+ * Zero-Trust Architecture:
+ * - Private keys NEVER leave your device
+ * - All signing happens locally using Ed25519
+ * - Keys are derived from passphrase using PBKDF2 (480,000 iterations)
+ */
+
+/**
+ * Derive an Ed25519 key pair from a passphrase.
+ * Uses PBKDF2-HMAC-SHA256 with 480,000 iterations.
+ */
+declare function deriveKeyPair(passphrase: string): KeyPair;
+/**
+ * Generate a device-bound passphrase.
+ *
+ * SECURITY BOUNDARY: This is a CONVENIENCE feature, not a security feature.
+ * For production, use an explicit passphrase.
+ */
+declare function deriveDevicePassphrase(): string;
+/**
+ * Canonicalize content for signing.
+ * Ensures deterministic JSON serialization.
+ */
+declare function canonicalize(obj: unknown): string;
+/**
+ * Hash content using SHA-256.
+ */
+declare function hashContent(content: CapsuleContent): string;
+/**
+ * Sign content with Ed25519.
+ */
+declare function sign(content: CapsuleContent, privateKey: Uint8Array): string;
+/**
+ * Verify an Ed25519 signature.
+ */
+declare function verify(content: CapsuleContent, signature: string, publicKey: string): boolean;
+/**
+ * Create a signed capsule.
+ */
+declare function createSignedCapsule(content: CapsuleContent, keyPair: KeyPair): SignedCapsule;
+/**
+ * Verify a signed capsule locally.
+ * No server required - pure cryptographic verification.
+ */
+declare function verifyCapsule(capsule: SignedCapsule): {
+    valid: boolean;
+    signatureValid: boolean;
+    hashValid: boolean;
+    errors: string[];
+};
+
+export { type CapsuleContent, type CapsuleProof, type CertifyOptions, type DataSource, type KeyPair, type ReasoningStep, type SignedCapsule, UATP, type UATPConfig, type VerificationResult, canonicalize, createSignedCapsule, deriveDevicePassphrase, deriveKeyPair, hashContent, sign, verify, verifyCapsule };