sekuire-protocol 0.1.1

Shared protocol types for the Sekuire Agent Identity Protocol
Documentation

Sekuire Protocol 🥝

Core protocol definitions and data structures for the Sekuire Agent Identity Protocol. This package provides the fundamental types, schemas, and serialization formats used across the Sekuire ecosystem.

Installation

Add this to your Cargo.toml:

[dependencies]
sekuire-protocol = "0.1.0"

Features

  • Type Definitions: Complete protocol data structures
  • Serialization: JSON/YAML support with Serde
  • JSON Schema: Schemars integration for API documentation
  • Database Support: Optional SQLx integration for backends
  • Cross-Language: Compatible with Rust, Python, TypeScript, and more

Core Types

Agent Identity

use sekuire_protocol::{Manifest, ProjectMetadata, IdentityConfig};

let manifest = Manifest {
    project: ProjectMetadata {
        name: "My AI Agent".to_string(),
        version: "1.0.0".to_string(),
        description: Some("A helpful AI assistant".to_string()),
        authors: vec!["Alice <alice@example.com>".to_string()],
        license: Some("MIT".to_string()),
    },
    identity: IdentityConfig {
        model: "gpt-4-0613".to_string(),
        system_prompt_path: "prompts/system.txt".to_string(),
        tools_path: "tools/tools.json".to_string(),
        system_prompt_hash: Some("abc123...".to_string()),
        tools_hash: Some("def456...".to_string()),
    },
};

Registry API

use sekuire_protocol::{PublishRequest, AgentResponse, VerificationStatus};

let request = PublishRequest {
    manifest: manifest,
    sekuire_id: "8a6ecffc...".to_string(),
    signature: "signature_bytes".to_string(),
    public_key: "public_key_hex".to_string(),
};

Handshake Protocol

use sekuire_protocol::{HandshakeHello, HandshakeWelcome, HandshakeAuth};

// Client initiates handshake
let hello = HandshakeHello {
    client_nonce: "random_32_byte_hex".to_string(),
};

// Agent responds
let welcome = HandshakeWelcome {
    agent_id: "8a6ecffc...".to_string(),
    agent_nonce: "another_random_32_byte_hex".to_string(),
    signature_c: "agent_signature_of_client_nonce".to_string(),
    credentials: vec![],
};

// Client completes handshake
let auth = HandshakeAuth {
    signature_a: "client_signature_of_agent_nonce".to_string(),
};

Data Structures

Manifest Configuration

The Manifest type defines an agent's identity and metadata:

pub struct Manifest {
    pub project: ProjectMetadata,
    pub identity: IdentityConfig,
}

pub struct ProjectMetadata {
    pub name: String,           // Agent name
    pub version: String,        // Semantic version
    pub description: Option<String>,  // Short description
    pub authors: Vec<String>,   // Author list
    pub license: Option<String>,  // License identifier
}

pub struct IdentityConfig {
    pub model: String,                    // Model identifier
    pub system_prompt_path: String,       // Path to system prompt
    pub tools_path: String,              // Path to tools definition
    pub system_prompt_hash: Option<String>,  // Blake3 hash of prompt
    pub tools_hash: Option<String>,      // Blake3 hash of tools
}

Verification Status

pub enum VerificationStatus {
    Unverified,  // New agent, not verified
    Pending,     // Verification in progress
    Verified,    // Successfully verified
    Suspended,   // Verification suspended
}

Registry Types

pub struct AgentResponse {
    pub sekuire_id: String,
    pub name: String,
    pub version: String,
    pub description: Option<String>,
    pub author_key: String,
    pub created_at: String,
    pub verification_status: VerificationStatus,
    pub reputation_score: i32,
}

pub struct ReputationResponse {
    pub score: i32,
    pub task_count: i32,
    pub verification_badge: Option<String>,
    pub recent_logs: Vec<ReputationLog>,
}

Handshake Messages

pub struct HandshakeHello {
    pub client_nonce: String,  // 32-byte hex string
}

pub struct HandshakeWelcome {
    pub agent_id: String,
    pub agent_nonce: String,   // 32-byte hex string
    pub signature_c: String,   // Agent signs client_nonce
    pub credentials: Vec<String>,  // Verifiable credentials
}

pub struct HandshakeAuth {
    pub signature_a: String,   // Client signs agent_nonce
}

JSON Schema Support

All types implement JsonSchema for automatic documentation generation:

use sekuire_protocol::Manifest;
use schemars::schema_for;

let schema = schema_for!(Manifest);
println!("{}", serde_json::to_string_pretty(&schema).unwrap());

Example JSON Schema output:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Manifest",
  "type": "object",
  "required": ["project", "identity"],
  "properties": {
    "project": { "$ref": "#/definitions/ProjectMetadata" },
    "identity": { "$ref": "#/definitions/IdentityConfig" }
  }
}

Database Integration

Enable the backend feature for SQLx support:

[dependencies]
sekuire-protocol = { version = "0.1.0", features = ["backend"] }

This adds database mappings for types like VerificationStatus:

// Automatic SQLx type mapping
#[derive(sqlx::Type)]
#[sqlx(type_name = "verification_status", rename_all = "snake_case")]
pub enum VerificationStatus {
    Unverified,
    Pending,
    Verified,
    Suspended,
}

Serialization Examples

JSON

use serde_json;

let manifest = create_manifest();
let json = serde_json::to_string_pretty(&manifest)?;
let parsed: Manifest = serde_json::from_str(&json)?;

YAML

use serde_yaml;

let manifest = create_manifest();
let yaml = serde_yaml::to_string(&manifest)?;
let parsed: Manifest = serde_yaml::from_str(&yaml)?;

Protocol Flow

The Sekuire protocol follows this sequence:

  1. Agent Registration: Agent publishes identity to registry
  2. Client Discovery: Client finds agent in registry
  3. Handshake Initiation: Client sends HandshakeHello
  4. Identity Proof: Agent responds with HandshakeWelcome
  5. Mutual Authentication: Client sends HandshakeAuth
  6. Verification Complete: Both parties are verified

Message Flow Diagram

Client                    Agent                    Registry
  |                         |                         |
  |---- HandshakeHello ---->|                         |
  |<-- HandshakeWelcome ---|                         |
  |                         |                         |
  |---- HandshakeAuth ----->|                         |
  |                         |                         |
  |---- Verify Agent ------>|                         |
  |<---- Agent Info --------|------------------------>|

Cryptographic Details

  • Signature Algorithm: Ed25519
  • Hash Algorithm: Blake3
  • Nonce Generation: Cryptographically secure random
  • Encoding: Hex for all binary data

Identity Hash Calculation

The sekuire_id is calculated as:

sekuire_id = Blake3(
    manifest.identity.model ||
    manifest.identity.system_prompt_content ||
    manifest.identity.tools_content ||
    manifest.project.name ||
    manifest.project.version
)

Error Handling

The protocol uses standard Result types for error handling:

use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct ProtocolError {
    pub code: String,
    pub message: String,
    pub details: Option<serde_json::Value>,
}

Version Compatibility

This package follows semantic versioning. Breaking changes will increment the major version.

  • 0.1.x: Initial protocol specification
  • 0.2.x: Added reputation system
  • 1.0.x: Stable protocol with backward compatibility

Dependencies

  • serde: Serialization framework
  • serde_json: JSON support
  • serde_yaml: YAML support
  • schemars: JSON schema generation
  • sqlx: Optional database support

Examples

See the examples/ directory for complete working examples:

  • basic_manifest.rs: Creating agent manifests
  • handshake_simulation.rs: Simulating handshake protocol
  • registry_client.rs: Registry API client
  • json_schema.rs: Generating API documentation

Language Support

This protocol definition is designed to be language-agnostic. Implementations exist for:

  • Rust (this package)
  • Python (sekuire-sdk-python)
  • TypeScript (@sekuire/protocol)
  • Go (community implementation)

Contributing

When contributing to the protocol:

  1. Maintain backward compatibility
  2. Update JSON schemas for new types
  3. Add comprehensive examples
  4. Document breaking changes
  5. Follow semantic versioning

License

Licensed under the MIT License. See LICENSE file for details.

Support