Comprehensive Explanation

sally

Implementation Overview

Sally is the vLEI Audit Reporting Agent, a specialized Python-based verification service implementation designed specifically for the verifiable Legal Entity Identifier (vLEI) ecosystem governed by GLEIF. The implementation serves as a critical infrastructure component that bridges credential presentations from vLEI ecosystem participants to GLEIF's reporting systems.

Programming Language: Python

Purpose and Scope: Sally functions as both a verification service and a reporting server, handling the complete workflow of receiving ACDC credential presentations, performing cryptographic validation, and forwarding verified data to external systems via webhooks. The implementation is purpose-built for the vLEI ecosystem and is not a general-purpose credential verifier.

Relationship to Protocol Specifications: Sally implements the verification side of the IPEX (Issuance and Presentation EXchange) protocol, specifically handling the presentation exchange workflow defined in the ACDC and KERI specifications. It operates as a verifier in the credential ecosystem, validating presentations against KERI key event logs and ACDC schemas.

Key Features & Capabilities

Core Verification Functionality

Sally performs three primary verification operations:

1. Structural Validation: Verifies that received credential presentations conform to the expected ACDC schema structure, ensuring all required fields are present and properly formatted according to JSON Schema definitions.

2. Cryptographic Verification: Validates the cryptographic integrity of presented credentials by:

   • Verifying digital signatures against the issuer's AID (Autonomic Identifier)
   • Checking SAID (Self-Addressing Identifier) integrity to ensure credential content hasn't been tampered with
   • Validating the complete KERI key event log chain to establish current key state
   • Verifying witness receipts if present in the credential presentation

3. Revocation Processing: Handles notices of credential revocation events by:

   • Receiving revocation notifications from the vLEI ecosystem
   • Verifying the authenticity of revocation events
   • Updating internal state to reflect revoked credentials
   • Forwarding revocation information to configured webhooks

Webhook Integration Architecture

Sally implements a webhook-based reporting mechanism that enables integration with external systems:

• HTTP POST Operations: After successful verification, Sally performs HTTP POST requests to configured webhook URLs
• Configurable Endpoints: Webhook URLs are configured at deployment time, allowing flexibility in routing verified credential data
• Payload Structure: The POST payload contains the verified credential data in a standardized format suitable for consumption by the GLEIF Reporting API
• Error Handling: Implements retry logic and error reporting for failed webhook deliveries

GLEIF Reporting API Integration

The primary use case for Sally is enabling the GLEIF Reporting API to maintain visibility into the vLEI ecosystem:

• Credential Tracking: Allows GLEIF to track which vLEI credentials have been issued to which Legal Entities
• Transparency: Provides transparency into the vLEI credential lifecycle
• Auditability: Creates an audit trail of credential presentations and revocations
• Ecosystem Monitoring: Enables GLEIF to monitor the health and activity of the vLEI ecosystem

Direct Mode Operation

Sally operates in what KERI terms direct mode, implementing a synchronous, peer-to-peer communication model:

• Synchronous Validation: Credential presentations are validated immediately upon receipt
• No Witness Dependency: Unlike indirect mode validators, Sally performs validation without requiring witness consensus
• Lower Security Posture: The direct mode architecture provides simpler bootstrapping but lower security guarantees compared to witness-based validation
• Future Enhancement: Documentation indicates potential future enhancement using watcher networks to establish verification thresholds, similar to distributed consensus systems

Installation & Setup

Based on the source documentation, Sally is available as open-source software maintained by GLEIF-IT on GitHub at the repository GLEIF-IT/sally.

Dependencies

Sally requires the following components to be operational:

1. KERI Infrastructure: Access to KERI witnesses or watchers for key event log verification
2. Schema Server: Access to a vLEI-server instance hosting ACDC schemas for validation
3. Network Connectivity: Ability to receive incoming credential presentations and make outbound webhook calls

Configuration

The implementation requires configuration of:

• Webhook URLs: Target endpoints for forwarding verified credential data
• Schema Sources: OOBI (Out-Of-Band Introduction) endpoints for resolving ACDC schemas
• Verification Parameters: Thresholds and policies for credential acceptance

Usage & API

Credential Presentation Workflow

The typical workflow for Sally involves:

1. Presentation Receipt: Sally receives a credential presentation from a vLEI ecosystem participant (typically via HTTP POST to Sally's endpoint)

2. Schema Resolution: Sally resolves the credential's schema using the schema SAID and configured OOBI endpoints

3. Structural Validation: The credential is validated against its JSON Schema to ensure structural correctness

4. Cryptographic Verification: Sally performs the following cryptographic checks:

   • Verifies the issuer's AID signature on the credential
   • Validates the credential's SAID matches its content
   • Checks the issuer's KEL for current key state
   • Verifies any attached witness receipts

5. Webhook Notification: Upon successful verification, Sally POSTs the verified credential data to configured webhook URLs

Revocation Handling

For revocation events:

1. Revocation Notice Receipt: Sally receives a revocation event notification

2. Event Verification: The revocation event is cryptographically verified:

   • Signature validation against the revoking authority's AID
   • TEL (Transaction Event Log) verification
   • Timestamp validation

3. State Update: Sally updates its internal state to reflect the revoked credential

4. Webhook Notification: The revocation is forwarded to configured webhooks

Integration with vLEI Ecosystem

Sally integrates with other vLEI ecosystem components:

• SignifyTS Wallets: Receives presentations from SignifyTS-based wallet implementations
• KERIA Agents: Accepts presentations from KERIA cloud agents
• vLEI-Server: Resolves schemas and OOBIs from the vLEI schema server
• GLEIF Reporting API: Forwards verified data to GLEIF's reporting infrastructure

Related Implementations

Verification Service Alternatives

While Sally is purpose-built for vLEI, the broader KERI ecosystem includes other verification implementations:

• Generic KERI Verifiers: General-purpose KERI verification libraries in KERIpy, KERIox, and other language implementations
• Custom Verifiers: Organizations can implement custom verification services using KERI libraries

Ecosystem Integration Points

Sally integrates with:

• KERIpy: The Python KERI implementation provides underlying verification primitives
• CESR: Uses Composable Event Streaming Representation for parsing credential data
• ACDC Libraries: Leverages ACDC parsing and validation libraries

Language-Specific Implementations

The KERI ecosystem includes verification capabilities in multiple languages:

• Python: KERIpy provides verification primitives used by Sally
• Rust: KERIox offers Rust-based verification
• TypeScript: SignifyTS includes client-side verification
• Swift: KERIml provides iOS/macOS verification capabilities

Implementation Architecture

Verification Pipeline

Sally implements a multi-stage verification pipeline:

Credential Presentation → Schema Resolution → Structural Validation → 
Cryptographic Verification → State Update → Webhook Notification

Each stage can fail independently, with appropriate error handling and logging at each step.

Security Model

Trust Assumptions:

• Sally trusts the KERI infrastructure (witnesses, watchers) for key state verification
• Sally trusts the schema server for schema definitions
• Sally does NOT trust the presenter - all credentials are cryptographically verified

Attack Surface:

• Network attacks on incoming presentations (mitigated by cryptographic verification)
• Schema poisoning attacks (mitigated by SAID-based schema integrity)
• Replay attacks (mitigated by KERI's first-seen policy)

Performance Considerations

Sally's performance characteristics:

• Synchronous Processing: Each presentation is processed synchronously, which may limit throughput
• Cryptographic Overhead: Signature verification and KEL validation add latency
• Network Dependencies: Performance depends on witness/watcher availability and schema server responsiveness

Deployment Context

Production Usage

Sally is deployed in the production vLEI ecosystem:

• GLEIF Infrastructure: GLEIF operates Sally instances to monitor vLEI credential activity
• QVI Integration: Qualified vLEI Issuers present credentials to Sally as part of the qualification process
• Reporting Pipeline: Sally feeds data into GLEIF's reporting and analytics systems

Testing and Development

Sally is used in vLEI development workflows:

• Local Testing: Developers run Sally locally to test credential presentation flows
• Integration Tests: The vlei-e2e repository includes end-to-end tests involving Sally
• Workflow Scripts: The qvi-software repository includes scripts that interact with Sally

Future Enhancements

Documentation indicates potential future enhancements:

Watcher Network Integration

Future versions may integrate with watcher networks to:

• Establish verification thresholds requiring multiple independent verifications
• Increase security guarantees beyond direct mode validation
• Enable distributed consensus on credential validity

Advanced Verification Policies

Potential enhancements include:

• Configurable verification policies based on credential type
• Risk-based verification with different security levels
• Integration with reputation systems for issuer trust scoring

Relationship to KERI Architecture

Sally exemplifies several KERI architectural principles:

End-Verifiability

Sally demonstrates end-verifiability by:

• Performing complete cryptographic verification without trusting intermediaries
• Validating the entire KEL chain to establish authoritative key state
• Not relying on external trust assertions

Ambient Verifiability

While Sally is a specific service, the credentials it verifies exhibit ambient verifiability:

• Anyone with access to the KEL can verify the same credentials
• Verification doesn't depend on Sally's specific infrastructure
• The cryptographic proofs are universally verifiable

Zero-Trust Architecture

Sally implements zero-trust principles:

• Never trusts, always verifies
• Cryptographically validates every presentation
• Maintains no persistent trust relationships with presenters

Ecosystem Role

Sally occupies a specific niche in the vLEI ecosystem:

• Not a Wallet: Sally doesn't store credentials or manage keys
• Not an Issuer: Sally doesn't create or sign credentials
• Not a Holder: Sally doesn't present credentials to other verifiers
• Pure Verifier: Sally's sole role is verification and reporting

This focused role makes Sally a critical but specialized component in the vLEI infrastructure, enabling GLEIF to maintain oversight of the ecosystem without becoming a centralized authority over credential issuance or usage.