@coolwithakay/uatp 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,446 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UATP: () => UATP,
+  bytesToHex: () => import_utils.bytesToHex,
+  canonicalize: () => canonicalize,
+  createSignedCapsule: () => createSignedCapsule,
+  deriveDevicePassphrase: () => deriveDevicePassphrase,
+  deriveKeyPair: () => deriveKeyPair,
+  hashContent: () => hashContent,
+  hexToBytes: () => import_utils.hexToBytes,
+  sign: () => sign2,
+  verify: () => verify2,
+  verifyCapsule: () => verifyCapsule
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/crypto.ts
+var ed = __toESM(require("@noble/ed25519"));
+var import_sha256 = require("@noble/hashes/sha256");
+var import_pbkdf2 = require("@noble/hashes/pbkdf2");
+var import_utils = require("@noble/hashes/utils");
+ed.etc.sha512Sync = (...m) => {
+  const { sha512 } = require("@noble/hashes/sha512");
+  return sha512(ed.etc.concatBytes(...m));
+};
+var PBKDF2_ITERATIONS = 48e4;
+var SALT_PREFIX = "uatp-v1-key-derivation";
+function deriveKeyPair(passphrase) {
+  const salt = new TextEncoder().encode(SALT_PREFIX);
+  const passphraseBytes = new TextEncoder().encode(passphrase);
+  const seed = (0, import_pbkdf2.pbkdf2)(import_sha256.sha256, passphraseBytes, salt, {
+    c: PBKDF2_ITERATIONS,
+    dkLen: 32
+  });
+  const privateKey = seed;
+  const publicKey = ed.getPublicKey(privateKey);
+  return { privateKey, publicKey };
+}
+function deriveDevicePassphrase() {
+  const factors = [];
+  if (typeof window !== "undefined") {
+    factors.push(window.navigator.userAgent);
+    factors.push(window.navigator.language);
+    factors.push(String(window.screen.width));
+    factors.push(String(window.screen.height));
+    factors.push(window.location.hostname);
+  } else if (typeof process !== "undefined") {
+    factors.push(process.platform);
+    factors.push(process.arch);
+    factors.push(process.env.USER || process.env.USERNAME || "");
+    factors.push(require("os").hostname());
+  }
+  const combined = factors.join(":");
+  const hash = (0, import_sha256.sha256)(new TextEncoder().encode(combined));
+  return `device_${(0, import_utils.bytesToHex)(hash).slice(0, 32)}`;
+}
+function canonicalize(obj) {
+  return JSON.stringify(obj, Object.keys(obj).sort());
+}
+function hashContent(content) {
+  const canonical = canonicalize(content);
+  const hash = (0, import_sha256.sha256)(new TextEncoder().encode(canonical));
+  return (0, import_utils.bytesToHex)(hash);
+}
+function sign2(content, privateKey) {
+  const canonical = canonicalize(content);
+  const messageBytes = new TextEncoder().encode(canonical);
+  const signature = ed.sign(messageBytes, privateKey);
+  return (0, import_utils.bytesToHex)(signature);
+}
+function verify2(content, signature, publicKey) {
+  try {
+    const canonical = canonicalize(content);
+    const messageBytes = new TextEncoder().encode(canonical);
+    const signatureBytes = (0, import_utils.hexToBytes)(signature);
+    const publicKeyBytes = (0, import_utils.hexToBytes)(publicKey);
+    return ed.verify(signatureBytes, messageBytes, publicKeyBytes);
+  } catch {
+    return false;
+  }
+}
+function generateCapsuleId() {
+  const timestamp = Date.now().toString(36);
+  const randomBytes = new Uint8Array(8);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(randomBytes);
+  } else {
+    const { randomBytes: nodeRandom } = require("crypto");
+    const buf = nodeRandom(8);
+    randomBytes.set(buf);
+  }
+  const random = (0, import_utils.bytesToHex)(randomBytes).slice(0, 8);
+  return `cap_${timestamp}_${random}`;
+}
+function createSignedCapsule(content, keyPair) {
+  const capsuleId = generateCapsuleId();
+  const contentHash = hashContent(content);
+  const signature = sign2(content, keyPair.privateKey);
+  const publicKey = (0, import_utils.bytesToHex)(keyPair.publicKey);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    capsuleId,
+    signature,
+    publicKey,
+    contentHash,
+    timestamp,
+    content
+  };
+}
+function verifyCapsule(capsule) {
+  const errors = [];
+  const computedHash = hashContent(capsule.content);
+  const hashValid = computedHash === capsule.contentHash;
+  if (!hashValid) {
+    errors.push("Content hash mismatch - capsule may have been tampered with");
+  }
+  const signatureValid = verify2(
+    capsule.content,
+    capsule.signature,
+    capsule.publicKey
+  );
+  if (!signatureValid) {
+    errors.push("Signature verification failed");
+  }
+  return {
+    valid: hashValid && signatureValid,
+    signatureValid,
+    hashValid,
+    errors
+  };
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "http://localhost:8000";
+var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION = "0.1.0";
+var UATP = class {
+  /**
+   * 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 = {}) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    if (this.baseUrl === DEFAULT_BASE_URL) {
+      console.warn("UATP client using localhost - set baseUrl for production");
+    }
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async certify(options) {
+    const {
+      task,
+      decision,
+      reasoning,
+      passphrase,
+      deviceBound = true,
+      confidence,
+      metadata = {},
+      requestTimestamp = true,
+      storeOnServer = false
+    } = options;
+    if (!task || typeof task !== "string") {
+      throw new Error("task must be a non-empty string");
+    }
+    if (!decision || typeof decision !== "string") {
+      throw new Error("decision must be a non-empty string");
+    }
+    if (!reasoning || !Array.isArray(reasoning) || reasoning.length === 0) {
+      throw new Error("reasoning must be a non-empty array");
+    }
+    let signingPassphrase;
+    if (passphrase) {
+      if (passphrase.length < 8) {
+        throw new Error("passphrase must be at least 8 characters");
+      }
+      signingPassphrase = passphrase;
+    } else if (deviceBound) {
+      console.warn(
+        "Using device-bound passphrase (DEVELOPMENT ONLY). For production, provide an explicit passphrase."
+      );
+      signingPassphrase = deriveDevicePassphrase();
+    } else {
+      throw new Error("Either provide a passphrase or set deviceBound=true");
+    }
+    const calculatedConfidence = confidence ?? reasoning.reduce((sum, step) => sum + (step.confidence || 0.5), 0) / reasoning.length;
+    const content = {
+      task,
+      decision,
+      reasoning_chain: reasoning,
+      confidence: calculatedConfidence,
+      metadata: {
+        ...metadata,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        sdk_version: SDK_VERSION,
+        signing_mode: "local"
+      }
+    };
+    const keyPair = deriveKeyPair(signingPassphrase);
+    const signed = createSignedCapsule(content, keyPair);
+    if (requestTimestamp) {
+      try {
+        const response = await this.fetch("/timestamp", {
+          method: "POST",
+          body: JSON.stringify({ hash: signed.contentHash })
+        });
+        if (response.ok) {
+          const tsData = await response.json();
+          signed.timestampToken = tsData.rfc3161;
+          signed.timestampTsa = tsData.tsa;
+        }
+      } catch (error) {
+        console.warn(
+          "Could not obtain timestamp. Capsule is still valid, just without external timestamp.",
+          error
+        );
+      }
+    }
+    if (storeOnServer) {
+      try {
+        const capsuleData = {
+          ...signed,
+          type: "reasoning_trace",
+          payload: content
+        };
+        const response = await this.fetch("/capsules/store", {
+          method: "POST",
+          body: JSON.stringify(capsuleData)
+        });
+        if (response.ok) {
+          signed.serverStored = true;
+          signed.proofUrl = `${this.baseUrl}/capsules/${signed.capsuleId}/verify`;
+        }
+      } catch (error) {
+        console.warn("Could not store on server. Capsule is still valid locally.", error);
+        signed.serverStored = false;
+      }
+    }
+    return signed;
+  }
+  /**
+   * Retrieve full cryptographic proof for a capsule.
+   *
+   * @example
+   * ```typescript
+   * const proof = await client.getProof('cap_abc123');
+   * console.log(proof.payload.task);
+   * ```
+   */
+  async getProof(capsuleId) {
+    const response = await this.fetch(`/capsules/${capsuleId}`);
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new Error(`Capsule ${capsuleId} not found`);
+      }
+      throw new Error(`Failed to retrieve proof: ${response.status}`);
+    }
+    const data = await response.json();
+    const capsule = data.capsule || data;
+    return {
+      capsuleId: capsule.capsule_id || capsule.id || capsuleId,
+      capsuleType: capsule.type || capsule.capsule_type || "unknown",
+      status: capsule.status || "unknown",
+      timestamp: new Date(capsule.timestamp),
+      payload: capsule.payload || {},
+      rawData: data
+    };
+  }
+  /**
+   * List capsules from the server.
+   *
+   * @example
+   * ```typescript
+   * const capsules = await client.listCapsules(10);
+   * for (const cap of capsules) {
+   *   console.log(cap.capsuleId, cap.status);
+   * }
+   * ```
+   */
+  async listCapsules(limit = 10) {
+    const response = await this.fetch(`/capsules?demo_mode=false&per_page=${limit}`);
+    if (!response.ok) {
+      throw new Error(`Failed to list capsules: ${response.status}`);
+    }
+    const data = await response.json();
+    return (data.capsules || []).slice(0, limit).map((item) => ({
+      capsuleId: item.capsule_id,
+      capsuleType: item.type || "unknown",
+      status: item.status || "unknown",
+      timestamp: new Date(item.timestamp),
+      payload: item.payload || {},
+      rawData: item
+    }));
+  }
+  /**
+   * 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) {
+    return verifyCapsule(capsule);
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async recordOutcome(capsuleId, outcome) {
+    const params = new URLSearchParams();
+    if (outcome.result) params.set("outcome_status", outcome.result);
+    if (outcome.notes) params.set("notes", outcome.notes);
+    if (outcome.customerSatisfaction) {
+      params.set("rating", String(outcome.customerSatisfaction));
+    }
+    const response = await this.fetch(
+      `/capsules/${capsuleId}/outcome?${params.toString()}`,
+      { method: "POST" }
+    );
+    if (response.status === 401) {
+      throw new Error("Authentication required. Outcome tracking requires a valid API key.");
+    }
+    if (response.status === 404) {
+      throw new Error(`Capsule ${capsuleId} not found`);
+    }
+    if (!response.ok) {
+      throw new Error(`Failed to record outcome: ${response.status}`);
+    }
+    return true;
+  }
+  /**
+   * Internal fetch wrapper with timeout and headers.
+   */
+  async fetch(path, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": `uatp-typescript-sdk/${SDK_VERSION}`,
+          ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {},
+          ...options.headers
+        }
+      });
+      return response;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UATP,
+  bytesToHex,
+  canonicalize,
+  createSignedCapsule,
+  deriveDevicePassphrase,
+  deriveKeyPair,
+  hashContent,
+  hexToBytes,
+  sign,
+  verify,
+  verifyCapsule
+});