@tacitprotocol/sdk 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tacitprotocol/sdk",
+  "version": "0.1.0",
+  "description": "The Tacit Protocol SDK — verify identity, prevent fraud, and broker trusted introductions with cryptographic proof",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "tacit",
+    "protocol",
+    "agent",
+    "ai-agent",
+    "social-networking",
+    "decentralized",
+    "did",
+    "verifiable-credentials",
+    "mcp",
+    "a2a",
+    "trust",
+    "introductions"
+  ],
+  "author": "Tacit Protocol Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tacitprotocol/tacit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "did-jwt": "^8.0.0",
+    "did-resolver": "^4.1.0",
+    "key-did-provider-ed25519": "^4.0.0",
+    "key-did-resolver": "^4.0.0",
+    "@stablelib/xchacha20poly1305": "^1.0.1",
+    "@stablelib/ed25519": "^1.0.3",
+    "uuid": "^9.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsup": "^8.0.0",
+    "vitest": "^1.3.0",
+    "@types/node": "^20.11.0",
+    "@types/uuid": "^9.0.0",
+    "eslint": "^8.56.0"
+  }
+}

package/src/core/agent.ts

@@ -0,0 +1,436 @@
+/**
+ * Tacit Protocol — Agent Core
+ *
+ * The TacitAgent is the primary interface for interacting with the
+ * Tacit Protocol. It represents a human's AI agent on the network.
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { createIdentity } from '../identity/did.js';
+import { AuthenticityEngine } from '../identity/authenticity.js';
+import type {
+  AgentIdentity,
+  AgentCard,
+  TacitConfig,
+  Intent,
+  IntentType,
+  MatchResult,
+  IntroProposal,
+  TacitEvent,
+  DomainType,
+  AuthenticityVector,
+  PrivacyLevel,
+} from '../types/index.js';
+
+// ─── Event Emitter ────────────────────────────────────────────────
+
+type EventHandler = (event: TacitEvent) => void | Promise<void>;
+
+class EventBus {
+  private handlers = new Map<string, Set<EventHandler>>();
+  private globalHandlers = new Set<EventHandler>();
+
+  on(type: string, handler: EventHandler): void {
+    if (!this.handlers.has(type)) {
+      this.handlers.set(type, new Set());
+    }
+    this.handlers.get(type)!.add(handler);
+  }
+
+  onAny(handler: EventHandler): void {
+    this.globalHandlers.add(handler);
+  }
+
+  off(type: string, handler: EventHandler): void {
+    this.handlers.get(type)?.delete(handler);
+  }
+
+  async emit(event: TacitEvent): Promise<void> {
+    const handlers = this.handlers.get(event.type) ?? new Set();
+    const all = [...handlers, ...this.globalHandlers];
+
+    for (const handler of all) {
+      try {
+        await handler(event);
+      } catch (error) {
+        console.error(`[Tacit] Event handler error for ${event.type}:`, error);
+      }
+    }
+  }
+}
+
+// ─── Agent Class ──────────────────────────────────────────────────
+
+export class TacitAgent {
+  private identity: AgentIdentity | null = null;
+  private config: TacitConfig;
+  private events = new EventBus();
+  private authenticityEngine = new AuthenticityEngine();
+  private intents = new Map<string, Intent>();
+  private proposals = new Map<string, IntroProposal>();
+  private connected = false;
+
+  constructor(config: TacitConfig) {
+    this.config = {
+      relayUrl: 'wss://relay.tacitprotocol.dev',
+      matchThresholds: {
+        autoPropose: 80,
+        suggest: 60,
+      },
+      preferences: {
+        introductionStyle: 'progressive',
+        initialAnonymity: true,
+        responseTime: '24h',
+        languages: ['en'],
+      },
+      ...config,
+    };
+
+    if (config.identity) {
+      this.identity = config.identity;
+    }
+  }
+
+  // ─── Static Factory ───────────────────────────────────────────
+
+  /**
+   * Create a new agent identity.
+   * Returns an AgentIdentity that can be passed to the constructor.
+   */
+  static async createIdentity(): Promise<AgentIdentity> {
+    return createIdentity();
+  }
+
+  // ─── Lifecycle ────────────────────────────────────────────────
+
+  /**
+   * Connect the agent to the Tacit network via a relay node.
+   */
+  async connect(): Promise<void> {
+    if (!this.identity) {
+      this.identity = await createIdentity();
+    }
+
+    // TODO: Establish WebSocket connection to relay node
+    // TODO: Publish Agent Card to the network
+    // TODO: Subscribe to intent matches
+
+    this.connected = true;
+
+    await this.events.emit({
+      type: 'connection:established',
+      endpoint: this.config.relayUrl!,
+    });
+  }
+
+  /**
+   * Disconnect the agent from the network.
+   * Active intents remain on the network until their TTL expires.
+   */
+  async disconnect(): Promise<void> {
+    // TODO: Close WebSocket connection
+    // TODO: Optionally withdraw all active intents
+
+    this.connected = false;
+  }
+
+  /**
+   * Check if the agent is connected to the network.
+   */
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  // ─── Identity ─────────────────────────────────────────────────
+
+  /**
+   * Get the agent's DID.
+   */
+  getDid(): string {
+    if (!this.identity) throw new Error('Agent has no identity. Call connect() first.');
+    return this.identity.did;
+  }
+
+  /**
+   * Get the agent's Agent Card.
+   */
+  getAgentCard(): AgentCard {
+    if (!this.identity) throw new Error('Agent has no identity. Call connect() first.');
+
+    return {
+      version: '0.1.0',
+      agent: {
+        did: this.identity.did,
+        name: this.config.profile?.name ?? 'Unnamed Tacit',
+        description: this.config.profile?.description ?? '',
+        created: this.identity.created.toISOString(),
+        protocols: ['tacit/discovery/v0.1', 'tacit/intro/v0.1'],
+        transport: {
+          type: 'didcomm/v2',
+          endpoint: this.config.relayUrl!,
+        },
+      },
+      domains: this.config.profile ? [{
+        type: this.config.profile.domain,
+        seeking: [this.config.profile.seeking],
+        offering: [this.config.profile.offering],
+        context: {},
+      }] : [],
+      authenticity: this.getAuthenticity(),
+      preferences: {
+        introductionStyle: this.config.preferences?.introductionStyle ?? 'progressive',
+        initialAnonymity: this.config.preferences?.initialAnonymity ?? true,
+        responseTime: this.config.preferences?.responseTime ?? '24h',
+        languages: this.config.preferences?.languages ?? ['en'],
+      },
+    };
+  }
+
+  /**
+   * Get the agent's current authenticity vector.
+   */
+  getAuthenticity(): AuthenticityVector {
+    if (!this.identity) {
+      return {
+        level: 'new',
+        score: 0,
+        dimensions: { tenure: 0, consistency: 0, attestations: 0, networkTrust: 0 },
+        verifiableCredentials: [],
+      };
+    }
+
+    return this.authenticityEngine.computeVector({
+      agentCreatedDate: this.identity.created,
+      consistencySignals: {
+        intentStability: 1.0, // New agent, no changes yet
+        profileConsistency: 1.0,
+        responseReliability: 0.5, // No track record
+        interactionQuality: 0.5,
+      },
+      credentials: [],
+      networkSignals: {
+        totalInteractions: 0,
+        positiveInteractions: 0,
+        totalIntros: 0,
+        successfulIntros: 0,
+        bidirectionalTrustEdges: 0,
+      },
+      lastActiveDate: new Date(),
+    });
+  }
+
+  // ─── Intents ──────────────────────────────────────────────────
+
+  /**
+   * Publish an intent to the network.
+   */
+  async publishIntent(params: {
+    type: IntentType;
+    domain: DomainType;
+    seeking: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    filters?: {
+      minAuthenticityScore?: number;
+      requiredCredentials?: string[];
+    };
+    privacyLevel?: PrivacyLevel;
+    ttlSeconds?: number;
+  }): Promise<Intent> {
+    if (!this.identity) throw new Error('Agent has no identity. Call connect() first.');
+
+    const intent: Intent = {
+      id: `intent:${this.identity.did.split(':').pop()}:${Date.now()}`,
+      agentDid: this.identity.did,
+      type: params.type,
+      domain: params.domain,
+      intent: {
+        seeking: params.seeking,
+        context: params.context ?? {},
+      },
+      filters: {
+        minAuthenticityScore: params.filters?.minAuthenticityScore ?? 50,
+        requiredCredentials: params.filters?.requiredCredentials ?? [],
+        excludedDomains: [],
+      },
+      privacyLevel: params.privacyLevel ?? 'filtered',
+      ttl: params.ttlSeconds ?? 604800, // 7 days default
+      created: new Date().toISOString(),
+      signature: '', // TODO: Sign with agent's private key
+    };
+
+    this.intents.set(intent.id, intent);
+
+    // TODO: Broadcast to relay node
+
+    await this.events.emit({ type: 'intent:published', intent });
+
+    return intent;
+  }
+
+  /**
+   * Withdraw an active intent.
+   */
+  async withdrawIntent(intentId: string): Promise<void> {
+    const intent = this.intents.get(intentId);
+    if (!intent) throw new Error(`Intent ${intentId} not found`);
+
+    this.intents.delete(intentId);
+
+    // TODO: Notify relay node of withdrawal
+  }
+
+  /**
+   * Get all active intents.
+   */
+  getActiveIntents(): Intent[] {
+    return Array.from(this.intents.values());
+  }
+
+  // ─── Proposals ────────────────────────────────────────────────
+
+  /**
+   * Handle an incoming match from the network.
+   * Called when another agent's intent is compatible with ours.
+   */
+  async handleMatch(match: MatchResult): Promise<void> {
+    const thresholds = this.config.matchThresholds!;
+
+    if (match.score.overall >= thresholds.autoPropose) {
+      // Auto-propose introduction
+      await this.proposeIntro(match);
+    } else if (match.score.overall >= thresholds.suggest) {
+      // Suggest to human for review
+      await this.events.emit({ type: 'intent:matched', match });
+    }
+    // Below suggest threshold: ignore
+  }
+
+  /**
+   * Create and send an introduction proposal.
+   */
+  async proposeIntro(match: MatchResult): Promise<IntroProposal> {
+    if (!this.identity) throw new Error('Agent has no identity.');
+
+    const proposal: IntroProposal = {
+      id: `proposal:${uuidv4()}`,
+      type: 'introduction',
+      initiator: {
+        agentDid: this.identity.did,
+        persona: {
+          displayName: this.config.profile?.name ?? 'Anonymous',
+          context: this.config.profile?.seeking ?? '',
+          anonymityLevel: this.config.preferences?.initialAnonymity ? 'pseudonymous' : 'identified',
+          sessionId: uuidv4(),
+        },
+      },
+      responder: {
+        agentDid: match.agents.responder,
+      },
+      match: {
+        score: match.score.overall,
+        rationale: this.generateRationale(match),
+        domain: 'professional', // TODO: derive from intent
+      },
+      terms: {
+        initialReveal: 'pseudonymous',
+        revealStages: ['domain_context', 'professional_background', 'identity'],
+        communicationChannel: 'tacit_direct',
+        expiry: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+      },
+      status: 'pending',
+      created: new Date().toISOString(),
+      signature: '', // TODO: Sign
+    };
+
+    this.proposals.set(proposal.id, proposal);
+
+    // TODO: Send proposal to responder via relay
+
+    return proposal;
+  }
+
+  /**
+   * Accept an introduction proposal.
+   * This is the human's explicit consent (one half of double opt-in).
+   */
+  async acceptProposal(proposalId: string): Promise<void> {
+    const proposal = this.proposals.get(proposalId);
+    if (!proposal) throw new Error(`Proposal ${proposalId} not found`);
+
+    if (!this.identity) throw new Error('Agent has no identity.');
+
+    // Determine which side we are
+    const isInitiator = proposal.initiator.agentDid === this.identity.did;
+
+    if (isInitiator) {
+      proposal.status = 'accepted_by_initiator';
+    } else {
+      proposal.status = 'accepted_by_responder';
+    }
+
+    // TODO: Send acceptance to the other party via relay
+    await this.events.emit({ type: 'proposal:accepted', proposal });
+  }
+
+  /**
+   * Decline an introduction proposal.
+   * The other party receives a generic "not a match" response.
+   */
+  async declineProposal(proposalId: string): Promise<void> {
+    const proposal = this.proposals.get(proposalId);
+    if (!proposal) throw new Error(`Proposal ${proposalId} not found`);
+
+    proposal.status = 'declined';
+    this.proposals.delete(proposalId);
+
+    // TODO: Send generic decline to the other party via relay
+    await this.events.emit({ type: 'proposal:declined', proposalId });
+  }
+
+  /**
+   * Get all pending proposals.
+   */
+  getPendingProposals(): IntroProposal[] {
+    return Array.from(this.proposals.values())
+      .filter(p => p.status === 'pending');
+  }
+
+  // ─── Events ───────────────────────────────────────────────────
+
+  /**
+   * Subscribe to specific event types.
+   */
+  on(type: string, handler: EventHandler): void {
+    this.events.on(type, handler);
+  }
+
+  /**
+   * Subscribe to all events.
+   */
+  onAny(handler: EventHandler): void {
+    this.events.onAny(handler);
+  }
+
+  /**
+   * Unsubscribe from an event type.
+   */
+  off(type: string, handler: EventHandler): void {
+    this.events.off(type, handler);
+  }
+
+  // ─── Helpers ──────────────────────────────────────────────────
+
+  private generateRationale(match: MatchResult): string {
+    const parts: string[] = [];
+    const b = match.score.breakdown;
+
+    if (b.intentAlignment > 0.8) parts.push('Strong intent alignment');
+    if (b.domainFit > 0.8) parts.push('Excellent domain fit');
+    if (b.authenticityCompatibility > 0.7) parts.push('High authenticity compatibility');
+    if (b.preferenceMatch > 0.7) parts.push('Good preference match');
+
+    return parts.length > 0
+      ? parts.join('. ') + '.'
+      : `Match score: ${match.score.overall}/100`;
+  }
+}

package/src/discovery/intent.ts

@@ -0,0 +1,209 @@
+/**
+ * Tacit Protocol — Intent Broadcasting & Discovery
+ *
+ * Handles the creation, publication, and discovery of intents
+ * on the Tacit network.
+ */
+
+import type {
+  Intent,
+  IntentType,
+  IntentStatus,
+  DomainType,
+  PrivacyLevel,
+  DID,
+} from '../types/index.js';
+
+// ─── Intent Builder ───────────────────────────────────────────────
+
+export class IntentBuilder {
+  private partial: Partial<Intent> = {};
+
+  constructor(agentDid: DID) {
+    this.partial.agentDid = agentDid;
+    this.partial.id = `intent:${agentDid.split(':').pop()}:${Date.now()}`;
+    this.partial.created = new Date().toISOString();
+    this.partial.privacyLevel = 'filtered';
+    this.partial.ttl = 604800; // 7 days
+    this.partial.filters = {
+      minAuthenticityScore: 50,
+      requiredCredentials: [],
+      excludedDomains: [],
+    };
+  }
+
+  type(type: IntentType): this {
+    this.partial.type = type;
+    return this;
+  }
+
+  domain(domain: DomainType): this {
+    this.partial.domain = domain;
+    return this;
+  }
+
+  seeking(seeking: Record<string, unknown>): this {
+    if (!this.partial.intent) {
+      this.partial.intent = { seeking: {}, context: {} };
+    }
+    this.partial.intent.seeking = seeking;
+    return this;
+  }
+
+  context(context: Record<string, unknown>): this {
+    if (!this.partial.intent) {
+      this.partial.intent = { seeking: {}, context: {} };
+    }
+    this.partial.intent.context = context;
+    return this;
+  }
+
+  privacy(level: PrivacyLevel): this {
+    this.partial.privacyLevel = level;
+    return this;
+  }
+
+  ttl(seconds: number): this {
+    this.partial.ttl = seconds;
+    return this;
+  }
+
+  minAuthenticity(score: number): this {
+    this.partial.filters!.minAuthenticityScore = score;
+    return this;
+  }
+
+  requireCredentials(...types: string[]): this {
+    this.partial.filters!.requiredCredentials = types;
+    return this;
+  }
+
+  build(): Intent {
+    if (!this.partial.type) throw new Error('Intent type is required');
+    if (!this.partial.domain) throw new Error('Intent domain is required');
+    if (!this.partial.intent?.seeking) throw new Error('Intent seeking is required');
+
+    return {
+      id: this.partial.id!,
+      agentDid: this.partial.agentDid!,
+      type: this.partial.type,
+      domain: this.partial.domain,
+      intent: this.partial.intent!,
+      filters: this.partial.filters!,
+      privacyLevel: this.partial.privacyLevel!,
+      ttl: this.partial.ttl!,
+      created: this.partial.created!,
+      signature: '', // Signed by agent before publishing
+    };
+  }
+}
+
+// ─── Intent Store ─────────────────────────────────────────────────
+
+/**
+ * Local intent storage with lifecycle management.
+ * In production, this connects to the relay network.
+ */
+export class IntentStore {
+  private intents = new Map<string, { intent: Intent; status: IntentStatus }>();
+
+  add(intent: Intent): void {
+    this.intents.set(intent.id, { intent, status: 'active' });
+  }
+
+  get(id: string): Intent | undefined {
+    return this.intents.get(id)?.intent;
+  }
+
+  getStatus(id: string): IntentStatus | undefined {
+    return this.intents.get(id)?.status;
+  }
+
+  setStatus(id: string, status: IntentStatus): void {
+    const entry = this.intents.get(id);
+    if (entry) entry.status = status;
+  }
+
+  withdraw(id: string): boolean {
+    const entry = this.intents.get(id);
+    if (!entry) return false;
+    entry.status = 'withdrawn';
+    return true;
+  }
+
+  /**
+   * Get all active intents (not expired, not withdrawn, not fulfilled).
+   */
+  getActive(): Intent[] {
+    const now = Date.now();
+    const active: Intent[] = [];
+
+    for (const [, entry] of this.intents) {
+      if (entry.status !== 'active') continue;
+
+      // Check TTL
+      const created = new Date(entry.intent.created).getTime();
+      if (now - created > entry.intent.ttl * 1000) {
+        entry.status = 'expired';
+        continue;
+      }
+
+      active.push(entry.intent);
+    }
+
+    return active;
+  }
+
+  /**
+   * Find intents that match a given query.
+   * This is the local equivalent of a relay query.
+   */
+  query(params: {
+    type?: IntentType;
+    domain?: DomainType;
+    minAuthenticity?: number;
+    keywords?: string[];
+  }): Intent[] {
+    return this.getActive().filter(intent => {
+      if (params.type && intent.type !== params.type) return false;
+      if (params.domain && intent.domain !== params.domain) return false;
+
+      if (params.keywords && params.keywords.length > 0) {
+        const intentText = JSON.stringify(intent.intent).toLowerCase();
+        const hasKeyword = params.keywords.some(kw =>
+          intentText.includes(kw.toLowerCase())
+        );
+        if (!hasKeyword) return false;
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Remove expired intents from the store.
+   */
+  cleanup(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [id, entry] of this.intents) {
+      if (entry.status === 'expired' || entry.status === 'withdrawn' || entry.status === 'fulfilled') {
+        this.intents.delete(id);
+        removed++;
+      }
+
+      // Check TTL for active intents
+      if (entry.status === 'active') {
+        const created = new Date(entry.intent.created).getTime();
+        if (now - created > entry.intent.ttl * 1000) {
+          entry.status = 'expired';
+          this.intents.delete(id);
+          removed++;
+        }
+      }
+    }
+
+    return removed;
+  }
+}