Process Flow

Stage 1: Schema Disclosure (Mechanical Protection)

The process begins with schema-based mechanical protection, where the discloser shares the schema of the data to be disclosed prior to sharing actual data contents. This initial stage:

1. Schema Transmission: The discloser sends the JSON Schema or schema SAID that defines the structure and format of the credential data
2. Structure Understanding: The disclosee examines the schema to understand what types of information will be shared, field structures, data types, and validation rules
3. Capability Assessment: The disclosee determines whether their systems can process the disclosed data format and whether the information meets their verification requirements
4. No Content Exposure: At this stage, no actual sensitive data contents are revealed—only the structural blueprint

This mechanical protection layer leverages CESR encoding and SAID-based content addressing to ensure schema integrity while maintaining content confidentiality.

Stage 2: Contract Disclosure (Legal Protection)

The second stage introduces contract-based legal protection through Ricardian contracts:

1. Contract Presentation: The discloser presents legal contracts that must be agreed to before data contents are shared
2. Terms Review: The disclosee reviews contractual obligations, which may include:
   • Data usage restrictions
   • Retention policies
   • Downstream sharing limitations
   • Liability frameworks
   • Chain-link-confidentiality obligations
3. Cryptographic Agreement: The disclosee cryptographically signs the contract using their AID (Autonomic Identifier), creating a non-repudiable commitment
4. Agreement Verification: The discloser verifies the disclosee's signature against their KEL (Key Event Log) to ensure authentic agreement

Stage 3: Graduated Content Disclosure

Once contractual agreements are cryptographically verified, the process enters graduated-disclosure of actual data contents:

1. Initial Compact Disclosure: The discloser may begin with compact-disclosure, revealing only SAIDs of field maps rather than full contents
2. Condition Verification: Before each progressive disclosure step, the discloser verifies that the disclosee has satisfied conditions (contractual agreements, technical capabilities, etc.)
3. Progressive Revelation: As conditions are met, the discloser progressively reveals more information through:
   • Partial-disclosure: Revealing some but not all field maps
   • Selective-disclosure: Disclosing specific attributes while keeping others blinded
   • Full-disclosure: Complete revelation of all credential data
4. Cryptographic Binding: Each disclosure stage maintains cryptographic proof chains through CESR-Proofs that verify back to the original issuer's commitment

Stage 4: Downstream Protection

The process includes mechanisms for protecting disclosed information as it moves downstream:

1. Chain-link-confidentiality: Contractual restrictions bind each recipient in the disclosure chain, creating obligations that extend to all subsequent recipients
2. Contingent-disclosure: Additional information release remains contingent upon ongoing satisfaction of conditions
3. Liability Propagation: Legal obligations propagate through the disclosure chain, ensuring downstream recipients inherit protection responsibilities

Technical Requirements

Cryptographic Requirements

Contractually-protected-disclosure depends on several cryptographic primitives and protocols:

1. SAID Protocol: Self-addressing identifiers provide content-addressable references that enable:

   • Compact disclosure without revealing content
   • Cryptographic binding between schemas, contracts, and data
   • Verification of content integrity across disclosure stages

2. CESR Encoding: Composable Event Streaming Representation ensures:

   • Dual text/binary encoding for interoperability
   • Self-framing primitives for stream parsing
   • Composability across different serialization domains

3. CESR-Proofs: Cryptographic proof attachments provide:

   • Non-repudiable signatures on schemas, contracts, and data
   • Transposable signature attachments across envelope boundaries
   • Verification of issuer commitments across all ACDC variants

4. AID Infrastructure: Autonomic identifiers enable:

   • Self-certifying identity for all participants
   • Key rotation and recovery through KELs
   • Verifiable control authority for signing operations

Protocol Requirements

The process operates within the IPEX protocol framework, which requires:

1. Message Exchange: Structured message flows for schema, contract, and data disclosure
2. State Management: Tracking of disclosure stages and condition satisfaction
3. Verification Workflows: Cryptographic verification of signatures, SAIDs, and KEL states
4. Error Handling: Graceful handling of verification failures, timeout conditions, and protocol violations

Timing Considerations

The process involves several timing-sensitive aspects:

1. Contract Expiration: Ricardian contracts may include time-bound validity periods
2. Credential Freshness: Verification of credential issuance dates and expiration
3. KEL Synchronization: Ensuring all parties have current key state information
4. Grace Periods: Handling of credential revocation grace periods (typically 90 days in vLEI ecosystem)

Error Handling

Robust error handling addresses:

1. Schema Validation Failures: When disclosee systems cannot process disclosed schema formats
2. Contract Rejection: When disclosee declines contractual terms
3. Signature Verification Failures: When cryptographic proofs fail validation
4. KEL Inconsistencies: When key state cannot be verified or shows duplicity
5. Timeout Conditions: When disclosure stages exceed time limits
6. Revocation Detection: When credentials are discovered to be revoked during disclosure

Usage Patterns

Pattern 1: High-Stakes Credential Presentation

In scenarios requiring maximum privacy protection and legal accountability:

1. Initial Contact: Discloser and disclosee establish communication channel
2. Schema Exchange: Discloser shares credential schema to establish data structure expectations
3. Contract Negotiation: Parties negotiate and agree to contractual terms
4. Minimal Disclosure: Discloser reveals only compact SAIDs initially
5. Progressive Trust: As trust develops, more detailed information is revealed
6. Full Disclosure: Complete data shared only when absolutely necessary

Pattern 2: Regulated Industry Compliance

For industries with strict data protection regulations:

1. Regulatory Framework: Contracts incorporate specific regulatory requirements (GDPR, HIPAA, etc.)
2. Audit Trail: All disclosure stages are logged for compliance auditing
3. Consent Management: Explicit consent captured at each disclosure stage
4. Data Minimization: Only information required for specific regulatory purposes is disclosed
5. Retention Policies: Contracts specify data retention and deletion requirements

Pattern 3: Cross-Organizational Data Sharing

For business-to-business credential exchanges:

1. Organizational Verification: Both parties verify organizational credentials (e.g., vLEI credentials)
2. Role-Based Disclosure: Contracts specify which organizational roles can access which data
3. Downstream Controls: Chain-link-confidentiality ensures data protection as it moves through organizational hierarchies
4. Liability Framework: Clear liability allocation for data breaches or misuse

Best Practices

1. Schema-First Design: Always disclose schemas before contracts to enable informed consent
2. Minimal Initial Disclosure: Start with compact disclosure and reveal more only as needed
3. Clear Contractual Language: Use unambiguous legal language in Ricardian contracts
4. Cryptographic Verification: Verify all signatures and SAIDs at each stage
5. State Tracking: Maintain clear records of disclosure stages and condition satisfaction
6. Timeout Management: Implement reasonable timeouts for each disclosure stage
7. Revocation Checking: Verify credential status before each disclosure stage
8. Audit Logging: Log all disclosure events for compliance and dispute resolution

Integration Considerations

1. KERI Infrastructure: Requires operational witness pools and watcher networks for KEL verification
2. Registry Integration: Connection to TEL (Transaction Event Log) registries for credential status checking
3. Schema Repositories: Access to schema registries for schema SAID resolution
4. Legal Framework: Integration with legal systems for contract enforcement
5. User Interface: Clear presentation of contractual terms and disclosure stages to end users

Implementation Challenges

Challenge 1: Contextual Linkability Mitigation

Even with contractually-protected-disclosure, contextual-linkability attacks remain a significant threat. The disclosee controls the presentation context and can capture auxiliary data that enables statistical correlation. Mitigation strategies include:

1. Context Blinding: Minimize contextual metadata captured during disclosure
2. Temporal Separation: Separate disclosure stages temporally to reduce correlation opportunities
3. Decoy Interactions: Generate decoy disclosure requests to obscure actual patterns
4. Legal Recourse: Strong contractual language prohibiting contextual data capture and correlation

Challenge 2: Contract Enforceability

Ricardian contracts provide legal frameworks, but enforcement depends on:

1. Jurisdictional Clarity: Clear specification of governing law and jurisdiction
2. Dispute Resolution: Defined mechanisms for resolving contract disputes
3. Liability Limits: Reasonable liability caps to ensure enforceability
4. Practical Remedies: Actionable remedies for contract violations

Challenge 3: Performance Optimization

Multi-stage disclosure processes can introduce latency. Optimization strategies include:

1. Parallel Verification: Verify signatures and SAIDs in parallel where possible
2. Caching: Cache verified schemas and contracts for repeated interactions
3. Batch Processing: Batch multiple disclosure requests when appropriate
4. Asynchronous Operations: Use asynchronous message patterns to avoid blocking

Relationship to Other Disclosure Mechanisms

Contractually-protected-disclosure represents the most elaborate form of disclosure in IPEX, explicitly including both:

1. Chain-link-confidentiality: Contractual restrictions that bind all downstream recipients
2. Contingent-disclosure: Conditional information release based on satisfaction of requirements

It builds upon and extends simpler disclosure mechanisms:

• Compact-disclosure: Used in initial stages to reveal only SAIDs
• Partial-disclosure: Employed for progressive field map revelation
• Selective-disclosure: Enables fine-grained attribute disclosure
• Graduated-disclosure: Provides the overall framework for progressive revelation

Security Properties

Contractually-protected-disclosure provides several critical security properties:

1. Authenticity: Cryptographic proof of credential origin through issuer signatures
2. Integrity: SAID-based verification ensures data has not been tampered with
3. Confidentiality: Progressive disclosure minimizes information exposure
4. Non-repudiation: Cryptographic signatures create non-repudiable commitments
5. Legal Accountability: Contractual frameworks provide recourse for violations
6. Correlation Resistance: Graduated disclosure and contractual protections minimize exploitable correlation

Governance and Ecosystem Context

Within the vLEI ecosystem governed by GLEIF, contractually-protected-disclosure is particularly relevant for:

1. ECR Credentials: Engagement Context Role credentials requiring privacy protection
2. OOR Credentials: Official Organizational Role credentials with sensitive organizational data
3. Cross-border Presentations: International credential presentations requiring jurisdictional clarity
4. High-value Transactions: Financial or legal transactions requiring maximum assurance

The vLEI Ecosystem Governance Framework provides additional policies and procedures that complement the technical mechanisms of contractually-protected-disclosure, creating a comprehensive framework for secure, privacy-preserving credential exchange in enterprise and regulatory contexts.

Key Rotation Handling: Account for key rotation events during multi-stage disclosure processes. Verify signatures against the key state at the time of signing, not current state.

Performance Optimization

1. Parallel Verification: Verify multiple signatures and SAIDs in parallel where possible. Use worker pools or async operations to maximize throughput.

2. Batch Processing: When disclosing to multiple recipients, batch common operations (schema transmission, contract distribution) to reduce overhead.

3. Caching Strategy: Implement multi-level caching: schema cache, contract cache, KEL state cache. Use LRU eviction policies with configurable size limits.

Security Hardening

1. Input Validation: Validate all received data against expected formats before processing. Reject malformed schemas, contracts, or ACDCs immediately.

2. Rate Limiting: Implement rate limiting on disclosure requests to prevent denial-of-service attacks. Typical limits: 10 requests/minute per AID.

3. Audit Logging: Log all disclosure events with timestamps, participant AIDs, and disclosure stages. Use append-only logs with cryptographic integrity protection.

Integration Patterns

1. KERI Infrastructure: Ensure connectivity to witness pools and watcher networks. Implement fallback mechanisms for witness unavailability.

2. TEL Integration: Connect to transaction event log registries for credential status checking. Implement caching of credential status with configurable TTL (typically 5 minutes).

3. User Interface: Provide clear visual indicators of disclosure stages to end users. Display contract terms in human-readable format with clear accept/reject options.

Testing Strategies

1. Unit Tests: Test each disclosure stage independently with mocked dependencies. Verify correct handling of success and failure cases.

2. Integration Tests: Test complete disclosure workflows across multiple implementations (keripy, signify, etc.) to ensure interoperability.

3. Security Tests: Test resistance to common attacks: replay attacks, man-in-the-middle, signature forgery, SAID manipulation.

Deployment Considerations

1. Configuration Management: Externalize configuration for timeouts, retry policies, cache sizes, and rate limits. Use environment-specific configurations.

2. Monitoring: Implement metrics collection for disclosure success rates, stage durations, and error frequencies. Set up alerts for anomalous patterns.

3. Scalability: Design for horizontal scalability. Disclosure state should be stored in distributed storage systems (Redis, etc.) rather than in-memory.

Common Pitfalls

1. Premature Data Disclosure: Never disclose data contents before verifying contract agreement signatures. This is the most critical security requirement.

2. Insufficient Verification: Always verify KEL state, not just signature validity. A valid signature from a compromised key is still invalid.

3. State Leakage: Ensure disclosure state is properly cleaned up after completion or failure. Lingering state can lead to information leakage.

4. Contextual Data Capture: Be aware that even with contractual protections, contextual linkability remains a threat. Minimize metadata capture during disclosure operations.