KERIA Agent Context

The glossary references KERIA (KERI Agent in the cloud) as the implementation context where SSE would be relevant. KERIA documentation describes a three-interface architecture:

1. Boot Interface: Agent worker initialization
2. Admin Interface: REST API for command and control
3. KERI Protocol Interface: CESR over HTTP for protocol messages

SSE would logically fit within the Admin Interface layer to provide notification delivery from the KERI system to client applications, though the source documents do not explicitly state this implementation detail.

Mailbox Notification Function

The term "mailbox notifications" in the SSE definition connects to KERI's asynchronous messaging architecture. KERI agents maintain mailboxes for inter-agent communication, and SSE appears to serve as the mechanism for alerting client interfaces when new messages arrive. However, the source documents provide no specifications for:

• Message format or structure
• Event types or categorization
• Filtering or subscription mechanisms
• Security or authentication requirements
• Connection lifecycle management

Distinguishing SSE from Core KERI Protocol

Important: SSE is not part of the KERI protocol specification itself. The protocol specifications for KERI, CESR, ACDC, OOBI, and IPEX do not reference SSE. Instead, SSE represents an implementation pattern used by agent software to communicate with user interfaces.

The KERI protocol defines:

• Key event structures (inception, rotation, interaction)
• Cryptographic verification mechanisms
• Witness coordination algorithms (KAACE/KAWA)
• Receipt and signature attachments
• CESR encoding for primitives and streams

SSE operates at a different layer, providing notification transport about events occurring within KERI systems rather than defining the events themselves.

Authentication Context: KRAM

The KERIA documentation references KRAM (KERI Request Authentication Method) for "replay attack protection" on requests to KERIA agents. The specification states:

"All requests from a web client must use KRAM (KERI Request Authentication Method) for replay attack protection. The method is essentially based on each request body needing to include a date time string field in ISO-8601 format that must be within an acceptable time window relative to the server's date time."

While KRAM is described for request authentication, the source documents do not specify how (or whether) KRAM applies to SSE connection establishment or event delivery. This represents a gap in the available documentation.

Signify Client Libraries

The glossary defines Signify as:

"a web client (key) event signing - and key pair creation app that minimizes the use of KERI on the client."

Signify client libraries (SignifyTS in TypeScript, SignifyPy in Python) implement the "signing at the edge" pattern where:

• Clients maintain control of private keys
• KERIA agents handle operational tasks
• Communication occurs between client and agent

SSE would logically provide the notification channel for agent-to-client updates in this architecture, enabling clients to respond to asynchronous events like:

• Credential offers received
• Presentation requests pending
• Witness receipts collected
• Key event processing completion

However, the source documents do not provide implementation specifications for how Signify libraries consume SSE notifications.

Limitations of Source Material

The available documentation reveals significant gaps in SSE coverage:

What Is NOT Documented

1. No API specifications: No endpoint URLs, request/response formats, or connection protocols
2. No message schemas: No JSON structures, event types, or data models
3. No implementation guidance: No code examples, configuration options, or deployment patterns
4. No performance characteristics: No latency requirements, throughput specifications, or scaling guidance
5. No security details: No authentication flows, authorization models, or encryption requirements
6. No error handling: No reconnection strategies, failure modes, or recovery procedures

What IS Documented

The source material establishes only:

• SSE provides "mailbox notifications"
• SSE is a "streaming service for the agent U/I"
• SSE enables getting "notifications from the KERI system itself"
• SSE relates to KERIA agent architecture
• SSE is distinct from core KERI protocol specifications

Broader KERI Ecosystem Context

Asynchronous Communication Patterns

KERI's architecture inherently supports asynchronous operations:

Witness coordination may require time for witnesses to receive, validate, and receipt key events. The KAACE (KERI Agreement Algorithm for Control Establishment) defines consensus mechanisms that don't require real-time synchronous responses.

IPEX (Issuance and Presentation Exchange) protocol supports multi-step credential exchanges where:

• Offers may be made and later accepted
• Presentations may be requested and later provided
• Verification may occur asynchronously

SSE provides a plausible notification mechanism for these asynchronous workflows, alerting user interfaces when state changes occur or actions are required.

Agent-Mediated Architecture

The glossary defines agent as:

"A representative for an identity. MAY require the use of a wallet. MAY support transfer."

And cloud agent as:

"Cloud agent is software that is installed on the cloud server instances in order to provide security, monitoring, and analysis solutions for the cloud."

KERIA implements a cloud agent architecture where agents perform operations on behalf of controllers. SSE fits this architecture by providing the communication channel through which agents inform clients about operation results and system state changes.

Comparison to Alternative Patterns

While the source documents do not compare SSE to alternatives, standard web architectures typically use:

Polling: Client repeatedly requests updates (inefficient, high latency) WebSockets: Bidirectional full-duplex communication (more complex than needed for notifications) Webhooks: Server pushes to client-provided endpoints (requires client infrastructure) SSE: Unidirectional server-to-client streaming (efficient for notifications)

SSE represents a reasonable choice for agent notification delivery given its:

• Native browser support
• Automatic reconnection
• Simplicity compared to WebSockets
• No client infrastructure requirements (unlike webhooks)

CESR and Protocol Layering

The KERI protocol heavily uses CESR (Composable Event Streaming Representation) for encoding cryptographic primitives and event streams. CESR provides:

• Text-binary composability: Lossless conversion between domains
• Self-framing primitives: Type, size, and value encoding
• Stream processing: Concatenated primitive handling

While SSE could theoretically transport CESR-encoded content, the source documents do not specify this. The glossary definition positions SSE as providing "notifications from the KERI system" rather than transporting KERI protocol messages directly.

The KERI Protocol Interface in KERIA is explicitly described as "CESR over HTTP," distinct from the Admin Interface where SSE would logically reside.

Documentation Status and Future Work

The minimal SSE documentation suggests this is either:

1. Implementation-defined: Specific KERIA implementations define SSE details
2. Standard web technology: Relies on general SSE knowledge without KERI-specific specification
3. Incomplete specification: Detailed SSE specifications may be pending or exist in separate documents not included in the glossary

The KERI ecosystem maintains multiple specifications:

• Core KERI protocol (draft-ssmith-keri)
• CESR encoding (draft-ssmith-cesr)
• ACDC credentials (ACDC specification)
• OOBI discovery (draft-ssmith-oobi)
• IPEX exchanges (draft-ssmith-ipex)
• CESR Proof Signatures (draft-pfeairheller-cesr-proof)

None of these specifications define SSE, confirming its status as implementation infrastructure rather than protocol requirement.

Practical Implications

For Implementers

Developers implementing KERI agents or clients must:

1. Understand the architectural role: SSE provides notification delivery for asynchronous operations
2. Recognize specification gaps: Implementation details are not standardized in available documentation
3. Reference existing implementations: KERIA and Signify codebases would provide practical guidance
4. Apply standard SSE practices: Use established SSE patterns from web development

For Integrators

Systems integrating with KERI agents should:

1. Expect asynchronous notifications: Plan for event-driven architectures
2. Handle connection lifecycle: Implement reconnection and error handling
3. Consult implementation documentation: Refer to specific agent documentation (e.g., KERIA) for details
4. Prepare for variability: Different agent implementations may use different notification mechanisms

Conclusion

The server-sent event entry in the KERI/GLEIF glossary represents a minimal stub definition that identifies SSE as a notification mechanism for agent user interfaces without providing detailed specifications. The available source material establishes only that SSE:

• Functions as "mailbox notifications"
• Provides "a streaming service for the agent U/I"
• Enables "notifications from the KERI system itself"
• Relates to KERIA agent architecture
• Is distinct from core KERI protocol specifications

The lack of detailed specifications suggests SSE serves as implementation infrastructure rather than a protocol-level requirement, with specific implementations (like KERIA) defining their own SSE usage patterns. Developers working with KERI agents should treat SSE as a standard web technology applied to agent notification scenarios, consulting specific agent implementation documentation for technical details not present in the protocol specifications or glossary definitions.

The minimal documentation reflects SSE's role as supporting infrastructure rather than a core KERI innovation—unlike CESR, ACDC, or KAACE, which represent novel protocol contributions requiring detailed specification.

• Subscribe to mailbox events from the KERIA agent's internal event system
• Monitor credential registry changes (TEL updates) for credential state notifications
• Track witness receipt arrivals to notify clients of consensus progress
• Integrate with IPEX workflows to provide exchange status updates

Testing

• Test reconnection behavior under various network conditions
• Verify message ordering and delivery guarantees
• Load test with realistic connection counts and message frequencies
• Test security controls (authentication, authorization, encryption)
• Verify resource cleanup when connections close