@tacitprotocol/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,554 @@
+/**
+ * Tacit Protocol — Core Type Definitions
+ * Version: 0.1.0
+ */
+type DID = `did:${string}:${string}`;
+interface AgentIdentity {
+    did: DID;
+    publicKey: Uint8Array;
+    privateKey?: Uint8Array;
+    created: Date;
+}
+type AnonymityLevel = 'anonymous' | 'pseudonymous' | 'semi-identified' | 'identified';
+interface SessionPersona {
+    displayName: string;
+    context: string;
+    anonymityLevel: AnonymityLevel;
+    sessionId: string;
+}
+interface AgentCard {
+    version: string;
+    agent: {
+        did: DID;
+        name: string;
+        description: string;
+        created: string;
+        protocols: string[];
+        transport: TransportConfig;
+    };
+    domains: Domain[];
+    authenticity: AuthenticityVector;
+    preferences: AgentPreferences;
+}
+interface TransportConfig {
+    type: 'didcomm/v2';
+    endpoint: string;
+}
+interface Domain {
+    type: DomainType;
+    seeking: string[];
+    offering: string[];
+    context: Record<string, string | string[] | number>;
+}
+type DomainType = 'professional' | 'dating' | 'local-services' | 'learning' | 'commerce' | 'custom';
+interface AgentPreferences {
+    introductionStyle: 'progressive' | 'direct';
+    initialAnonymity: boolean;
+    responseTime: string;
+    languages: string[];
+}
+interface AuthenticityVector {
+    level: TrustLevel;
+    score: number;
+    dimensions: AuthenticityDimensions;
+    verifiableCredentials: VerifiableCredential[];
+}
+interface AuthenticityDimensions {
+    tenure: number;
+    consistency: number;
+    attestations: number;
+    networkTrust: number;
+}
+type TrustLevel = 'new' | 'emerging' | 'established' | 'trusted' | 'exemplary';
+interface VerifiableCredential {
+    type: string;
+    issuer: DID;
+    claim: string;
+    issued: string;
+    signature?: string;
+}
+interface Intent {
+    id: string;
+    agentDid: DID;
+    type: IntentType;
+    domain: DomainType;
+    intent: {
+        seeking: Record<string, unknown>;
+        context: Record<string, unknown>;
+    };
+    filters: IntentFilters;
+    privacyLevel: PrivacyLevel;
+    ttl: number;
+    created: string;
+    signature: string;
+}
+type IntentType = 'introduction' | 'service' | 'collaboration' | 'mentorship' | 'commerce';
+type PrivacyLevel = 'public' | 'filtered' | 'private';
+interface IntentFilters {
+    minAuthenticityScore: number;
+    requiredCredentials: string[];
+    excludedDomains: string[];
+}
+type IntentStatus = 'created' | 'published' | 'active' | 'matched' | 'fulfilled' | 'expired' | 'withdrawn';
+interface MatchResult {
+    matchId: string;
+    agents: {
+        initiator: DID;
+        responder: DID;
+    };
+    score: MatchScore;
+    timestamp: string;
+}
+interface MatchScore {
+    overall: number;
+    breakdown: {
+        intentAlignment: number;
+        domainFit: number;
+        authenticityCompatibility: number;
+        preferenceMatch: number;
+        timingFit: number;
+    };
+}
+type MatchAction = 'auto-propose' | 'suggest' | 'ignore';
+interface IntroProposal {
+    id: string;
+    type: IntentType;
+    initiator: {
+        agentDid: DID;
+        persona: SessionPersona;
+    };
+    responder: {
+        agentDid: DID;
+        persona?: SessionPersona;
+    };
+    match: {
+        score: number;
+        rationale: string;
+        domain: DomainType;
+    };
+    terms: IntroTerms;
+    status: ProposalStatus;
+    created: string;
+    signature: string;
+}
+interface IntroTerms {
+    initialReveal: AnonymityLevel;
+    revealStages: RevealStage[];
+    communicationChannel: string;
+    expiry: string;
+}
+type RevealStage = 'domain_context' | 'professional_background' | 'personal_background' | 'identity' | 'direct_contact';
+type ProposalStatus = 'pending' | 'accepted_by_initiator' | 'accepted_by_responder' | 'active' | 'completed' | 'declined' | 'expired' | 'withdrawn';
+interface ServiceIntent {
+    serviceType: string;
+    description: string;
+    location?: {
+        city: string;
+        radiusKm: number;
+    };
+    budget?: {
+        currency: string;
+        max: number;
+    };
+    urgency: string;
+    requirements: {
+        minAuthenticity: number;
+        requiredCredentials: string[];
+    };
+}
+interface ServiceAttestation {
+    type: 'ServiceAttestation';
+    issuer: DID;
+    subject: DID;
+    claims: {
+        serviceType: string;
+        completed: boolean;
+        qualityRating: number;
+        onTime: boolean;
+        wouldRecommend: boolean;
+    };
+    issued: string;
+    signature: string;
+}
+type TacitEvent = {
+    type: 'intent:published';
+    intent: Intent;
+} | {
+    type: 'intent:matched';
+    match: MatchResult;
+} | {
+    type: 'intent:expired';
+    intentId: string;
+} | {
+    type: 'proposal:received';
+    proposal: IntroProposal;
+} | {
+    type: 'proposal:accepted';
+    proposal: IntroProposal;
+} | {
+    type: 'proposal:declined';
+    proposalId: string;
+} | {
+    type: 'intro:started';
+    proposal: IntroProposal;
+} | {
+    type: 'intro:context-revealed';
+    stage: RevealStage;
+    data: Record<string, unknown>;
+} | {
+    type: 'intro:completed';
+    proposalId: string;
+} | {
+    type: 'connection:established';
+    endpoint: string;
+} | {
+    type: 'connection:lost';
+    reason: string;
+} | {
+    type: 'error';
+    error: Error;
+};
+interface TacitConfig {
+    identity?: AgentIdentity;
+    relayUrl?: string;
+    profile?: {
+        name: string;
+        description?: string;
+        domain: DomainType;
+        seeking: string;
+        offering: string;
+    };
+    matchThresholds?: {
+        autoPropose: number;
+        suggest: number;
+    };
+    preferences?: Partial<AgentPreferences>;
+}
+interface RelayConfig {
+    url: string;
+    maxRetries: number;
+    retryDelayMs: number;
+    heartbeatIntervalMs: number;
+}
+
+/**
+ * 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.
+ */
+
+type EventHandler = (event: TacitEvent) => void | Promise<void>;
+declare class TacitAgent {
+    private identity;
+    private config;
+    private events;
+    private authenticityEngine;
+    private intents;
+    private proposals;
+    private connected;
+    constructor(config: TacitConfig);
+    /**
+     * Create a new agent identity.
+     * Returns an AgentIdentity that can be passed to the constructor.
+     */
+    static createIdentity(): Promise<AgentIdentity>;
+    /**
+     * Connect the agent to the Tacit network via a relay node.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect the agent from the network.
+     * Active intents remain on the network until their TTL expires.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if the agent is connected to the network.
+     */
+    isConnected(): boolean;
+    /**
+     * Get the agent's DID.
+     */
+    getDid(): string;
+    /**
+     * Get the agent's Agent Card.
+     */
+    getAgentCard(): AgentCard;
+    /**
+     * Get the agent's current authenticity vector.
+     */
+    getAuthenticity(): AuthenticityVector;
+    /**
+     * Publish an intent to the network.
+     */
+    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>;
+    /**
+     * Withdraw an active intent.
+     */
+    withdrawIntent(intentId: string): Promise<void>;
+    /**
+     * Get all active intents.
+     */
+    getActiveIntents(): Intent[];
+    /**
+     * Handle an incoming match from the network.
+     * Called when another agent's intent is compatible with ours.
+     */
+    handleMatch(match: MatchResult): Promise<void>;
+    /**
+     * Create and send an introduction proposal.
+     */
+    proposeIntro(match: MatchResult): Promise<IntroProposal>;
+    /**
+     * Accept an introduction proposal.
+     * This is the human's explicit consent (one half of double opt-in).
+     */
+    acceptProposal(proposalId: string): Promise<void>;
+    /**
+     * Decline an introduction proposal.
+     * The other party receives a generic "not a match" response.
+     */
+    declineProposal(proposalId: string): Promise<void>;
+    /**
+     * Get all pending proposals.
+     */
+    getPendingProposals(): IntroProposal[];
+    /**
+     * Subscribe to specific event types.
+     */
+    on(type: string, handler: EventHandler): void;
+    /**
+     * Subscribe to all events.
+     */
+    onAny(handler: EventHandler): void;
+    /**
+     * Unsubscribe from an event type.
+     */
+    off(type: string, handler: EventHandler): void;
+    private generateRationale;
+}
+
+/**
+ * Tacit Protocol — DID Identity Management
+ *
+ * Handles creation, resolution, and management of W3C Decentralized Identifiers
+ * for Tacit agents. Uses did:key method for simplicity in v0.1.
+ */
+
+/**
+ * Create a did:key identifier from a public key.
+ * did:key encodes the public key directly in the DID string.
+ *
+ * Format: did:key:z{multibase-encoded-multicodec-public-key}
+ * For Ed25519: multicodec prefix is 0xed01
+ */
+declare function publicKeyToDid(publicKey: Uint8Array): DID;
+/**
+ * Create a new agent identity with a fresh keypair and DID.
+ */
+declare function createIdentity(): Promise<AgentIdentity>;
+/**
+ * Resolve a DID to its public key.
+ * For did:key, the public key is embedded in the DID itself.
+ */
+declare function resolveDid(did: DID): {
+    publicKey: Uint8Array;
+} | null;
+/**
+ * Sign arbitrary data with the agent's private key.
+ */
+declare function sign(data: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;
+/**
+ * Verify a signature against a public key.
+ */
+declare function verify(data: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+
+/**
+ * Tacit Protocol — Authenticity Vector Engine
+ *
+ * Computes and manages the multi-dimensional trust score that
+ * replaces self-reported profiles with verifiable behavioral signals.
+ */
+
+declare class AuthenticityEngine {
+    /**
+     * Compute the tenure dimension score.
+     * Linear growth over 365 days, capped at 1.0.
+     */
+    computeTenure(agentCreatedDate: Date, now?: Date): number;
+    /**
+     * Compute the consistency dimension score.
+     * Based on behavioral stability signals over time.
+     */
+    computeConsistency(signals: ConsistencySignals): number;
+    /**
+     * Compute the attestation dimension score.
+     * Based on third-party verifiable credentials.
+     */
+    computeAttestations(credentials: VerifiableCredential[]): number;
+    /**
+     * Compute the network trust dimension score.
+     * Based on the quality of the agent's network relationships.
+     *
+     * This is a simplified version — production implementations
+     * should use a full PageRank-style algorithm.
+     */
+    computeNetworkTrust(signals: NetworkTrustSignals): number;
+    /**
+     * Compute the full authenticity vector from all dimensions.
+     */
+    computeVector(params: {
+        agentCreatedDate: Date;
+        consistencySignals: ConsistencySignals;
+        credentials: VerifiableCredential[];
+        networkSignals: NetworkTrustSignals;
+        lastActiveDate?: Date;
+    }): AuthenticityVector;
+    /**
+     * Convert a numeric score to a trust level.
+     */
+    scoreToLevel(score: number): TrustLevel;
+    /**
+     * Check if an agent meets minimum authenticity requirements.
+     */
+    meetsMinimum(vector: AuthenticityVector, minScore: number): boolean;
+}
+interface ConsistencySignals {
+    /** 0-1: How stable the agent's intents have been over time */
+    intentStability: number;
+    /** 0-1: How consistent the profile claims have been */
+    profileConsistency: number;
+    /** 0-1: How reliably the agent responds to proposals */
+    responseReliability: number;
+    /** 0-1: Quality ratings from completed interactions */
+    interactionQuality: number;
+}
+interface NetworkTrustSignals {
+    /** Total number of interactions this agent has had */
+    totalInteractions: number;
+    /** Number of interactions rated positively by the other party */
+    positiveInteractions: number;
+    /** Total introduction proposals that reached completion */
+    totalIntros: number;
+    /** Intros that both parties rated as successful */
+    successfulIntros: number;
+    /** Number of agents that mutually trust this agent */
+    bidirectionalTrustEdges: number;
+}
+
+/**
+ * Tacit Protocol — Intent Broadcasting & Discovery
+ *
+ * Handles the creation, publication, and discovery of intents
+ * on the Tacit network.
+ */
+
+declare class IntentBuilder {
+    private partial;
+    constructor(agentDid: DID);
+    type(type: IntentType): this;
+    domain(domain: DomainType): this;
+    seeking(seeking: Record<string, unknown>): this;
+    context(context: Record<string, unknown>): this;
+    privacy(level: PrivacyLevel): this;
+    ttl(seconds: number): this;
+    minAuthenticity(score: number): this;
+    requireCredentials(...types: string[]): this;
+    build(): Intent;
+}
+/**
+ * Local intent storage with lifecycle management.
+ * In production, this connects to the relay network.
+ */
+declare class IntentStore {
+    private intents;
+    add(intent: Intent): void;
+    get(id: string): Intent | undefined;
+    getStatus(id: string): IntentStatus | undefined;
+    setStatus(id: string, status: IntentStatus): void;
+    withdraw(id: string): boolean;
+    /**
+     * Get all active intents (not expired, not withdrawn, not fulfilled).
+     */
+    getActive(): Intent[];
+    /**
+     * 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[];
+    /**
+     * Remove expired intents from the store.
+     */
+    cleanup(): number;
+}
+
+/**
+ * Tacit Protocol — Match Scoring Engine
+ *
+ * Computes compatibility scores between two agents based on their
+ * intents, domains, authenticity, and preferences.
+ */
+
+declare class MatchScorer {
+    private thresholds;
+    constructor(thresholds?: {
+        autoPropose?: number;
+        suggest?: number;
+    });
+    /**
+     * Score the compatibility between two agents based on their intents and cards.
+     */
+    score(params: {
+        initiator: {
+            intent: Intent;
+            card: AgentCard;
+        };
+        responder: {
+            intent: Intent;
+            card: AgentCard;
+        };
+    }): MatchResult;
+    /**
+     * Determine what action to take based on a match score.
+     */
+    determineAction(score: number): MatchAction;
+    /**
+     * Score how well the two intents complement each other.
+     * A seeking-offering match scores highest.
+     */
+    private scoreIntentAlignment;
+    /**
+     * Score the domain overlap between two intents.
+     */
+    private scoreDomainFit;
+    /**
+     * Score whether both agents meet each other's authenticity requirements.
+     */
+    private scoreAuthenticityCompatibility;
+    /**
+     * Score preference compatibility (communication style, timing, language).
+     */
+    private scorePreferenceMatch;
+    /**
+     * Score timing compatibility — are both intents active and aligned in urgency?
+     */
+    private scoreTimingFit;
+}
+
+export { type AgentCard, type AgentIdentity, type AgentPreferences, type AnonymityLevel, type AuthenticityDimensions, AuthenticityEngine, type AuthenticityVector, type ConsistencySignals, type DID, type Domain, type DomainType, type Intent, IntentBuilder, type IntentFilters, type IntentStatus, IntentStore, type IntentType, type IntroProposal, type IntroTerms, type MatchAction, type MatchResult, type MatchScore, MatchScorer, type NetworkTrustSignals, type PrivacyLevel, type ProposalStatus, type RelayConfig, type RevealStage, type ServiceAttestation, type ServiceIntent, type SessionPersona, TacitAgent, type TacitConfig, type TacitEvent, type TransportConfig, type TrustLevel, type VerifiableCredential, createIdentity, publicKeyToDid, resolveDid, sign, verify };