Skip to content

AUDIT_SCOPE.md

Latest commit

 

History

History
610 lines (472 loc) · 21.3 KB

AUDIT_SCOPE.md

File metadata and controls

610 lines (472 loc) · 21.3 KB
Raw

TrustLink Security Audit Scope

Project: TrustLink - On-Chain Attestation & Verification System
Version: 0.1.0
Blockchain: Stellar Soroban
Audit Type: Pre-Mainnet Security Audit
Prepared: March 26, 2026

Executive Summary

TrustLink is a Soroban smart contract providing a reusable trust layer for the Stellar blockchain. It enables authorized issuers to create, manage, and revoke attestations about wallet addresses, allowing other contracts and applications to verify claims before executing financial operations.

This audit scope document defines the boundaries, objectives, and deliverables for a comprehensive security review of TrustLink before mainnet deployment with real funds.

1. Project Overview

Purpose

TrustLink solves decentralized identity verification and trust establishment on-chain. Instead of each application building its own KYC/verification system, TrustLink provides shared attestation infrastructure queryable by any smart contract.

Key Features

  • Authorized Issuers: Admin-controlled registry of trusted attestation issuers
  • Claim Type Registry: Admin-managed registry of standard claim types with descriptions
  • Flexible Claims: Support for any claim type (KYC_PASSED, ACCREDITED_INVESTOR, MERCHANT_VERIFIED, etc.)
  • Expiration Support: Optional time-based expiration for attestations
  • Historical Import: Admin can import externally verified attestations with original timestamps
  • Cross-Chain Bridge Support: Trusted bridge contracts can bring attestations from other chains on-chain
  • Configurable Fees: Admin can require a token-denominated fee for native attestation creation
  • Revocation: Issuers can revoke attestations at any time
  • Deterministic IDs: Attestations have unique, reproducible identifiers
  • Event Emission: All state changes emit events for off-chain indexing
  • Multi-Sig Support: M-of-N issuer co-signing for high-value claims
  • GDPR Compliance: Soft-delete mechanism for right to erasure
  • Pagination: Efficient listing of attestations per subject or issuer

Deployment Target

  • Mainnet: Stellar Production Network
  • Real Funds: Yes - fee collection and potential token transfers
  • User Impact: High - affects KYC/verification for regulated financial protocols

2. Audit Scope

In Scope

2.1 Smart Contract Code

  • Location: src/ directory
  • Language: Rust (Soroban SDK v21.0.0)
  • Files:
    • src/lib.rs - Main contract implementation (40+ public functions)
    • src/types.rs - Data structures, error definitions, attestation schema
    • src/storage.rs - Storage patterns, TTL management, pagination logic
    • src/validation.rs - Authorization and access control checks
    • src/events.rs - Event emission for off-chain indexing
    • src/test.rs - Unit tests

Functions to Review (40+):

  • Initialization: initialize, transfer_admin, get_admin
  • Issuer Management: register_issuer, remove_issuer, is_issuer, update_issuer_tier, get_issuer_metadata, set_issuer_metadata
  • Claim Type Registry: register_claim_type, get_claim_type_description, list_claim_types
  • Attestation Creation: create_attestation, create_attestations_batch, create_attestation_from_template
  • Attestation Queries: get_attestation, has_valid_claim, has_valid_claim_from_issuer, has_any_claim, has_all_claims, get_valid_claims, get_attestations_by_tag
  • Attestation Management: revoke_attestation, revoke_attestations_batch, renew_attestation, update_expiration, request_deletion
  • Pagination: get_subject_attestations, get_issuer_attestations
  • Templates: create_template, get_template, list_templates
  • Multi-Sig: propose_attestation, cosign_attestation
  • Endorsements: endorse_attestation
  • Bridge Support: register_bridge, bridge_attestation
  • Fee Management: set_fee, get_fee_config
  • Import: import_attestation
  • Emergency: pause, unpause, is_paused
  • Hooks: register_expiration_hook, remove_expiration_hook
  • Health: health_check, get_version, get_contract_metadata, get_config, get_expiring_attestations, get_issuer_expiring_attestations

2.2 Authorization & Access Control

  • Admin-only functions and their guards
  • Issuer registry enforcement
  • Subject authentication for deletion requests
  • Bridge contract authorization
  • Multi-sig threshold validation
  • Pause mechanism enforcement

2.3 Data Integrity & Storage

  • Deterministic ID generation (SHA-256 based)
  • Collision prevention and uniqueness guarantees
  • Storage key management and TTL policies
  • Pagination logic and boundary conditions
  • Duplicate attestation prevention
  • Revocation flag handling

2.4 Business Logic

  • Expiration validation and enforcement
  • Fee collection and token transfer correctness
  • Batch operation atomicity and error handling
  • Multi-sig proposal lifecycle (creation, co-signing, expiry)
  • Endorsement chain validation
  • Bridge attestation source tracking
  • Template instantiation and override logic
  • Claim type registry consistency

2.5 Event Emission

  • Event completeness (all state changes emit events)
  • Event accuracy (correct data in topics and data fields)
  • Event ordering and consistency
  • Off-chain indexer compatibility

2.6 GDPR Compliance

  • Soft-delete implementation (request_deletion)
  • Deletion flag enforcement in queries
  • Compliance audit trail (DeletionRequested events)
  • Data minimization practices

2.7 Cross-Contract Interactions

  • External contract calls (expiration hooks, fee token transfers)
  • Callback trust boundaries
  • Reentrancy considerations
  • Error propagation from external calls

2.8 Test Coverage

  • Unit tests in src/test.rs (30+ tests)
  • Authorization tests in tests/authorization.rs
  • Integration tests in tests/integration_test.rs
  • Fuzz tests in tests/id_generation_fuzz.rs
  • Example contracts: examples/kyc-token/, examples/anchor-integration/

Out of Scope

2.9 Exclusions

  • Indexer Application: Off-chain Node.js/TypeScript indexer (indexer/ directory) - separate audit recommended
  • SDK Implementation: TypeScript SDK (sdk/typescript/) - separate audit recommended
  • Infrastructure: Docker, Kubernetes, deployment automation
  • Stellar Network: Soroban runtime, Horizon API, consensus mechanism
  • Third-Party Dependencies: Soroban SDK itself (assumed audited by Stellar)
  • Documentation Quality: Grammar, clarity (content accuracy is in scope)
  • Build System: Makefile, CI/CD configuration
  • Example Contracts: KYC token and anchor integration examples (reference implementations only)

3. Security Objectives

3.1 Primary Objectives

  1. Authorization Correctness

    • Verify all functions enforce correct access control
    • Confirm admin, issuer, and subject roles are properly scoped
    • Validate that de-registered issuers cannot perform privileged actions
    • Ensure multi-sig thresholds are correctly enforced

  2. Data Integrity

    • Confirm deterministic ID generation prevents collisions
    • Verify attestation immutability (only revoked flag and expiration can change)
    • Validate storage key isolation and no cross-contamination
    • Ensure pagination logic handles edge cases correctly

  3. State Consistency

    • Verify batch operations are atomic or fail safely
    • Confirm event emission matches state changes
    • Validate that pause mechanism blocks all write operations
    • Ensure TTL expiry doesn't cause data loss or inconsistency

  4. Threat Model Coverage

    • Prevent unauthorized issuance
    • Prevent self-attestation
    • Prevent replay attacks
    • Prevent admin impersonation
    • Prevent issuer bypass after de-registration
    • Prevent unauthorized revocation
    • Prevent unauthorized admin transfer

  5. Compliance & Privacy

    • Verify GDPR right to erasure implementation
    • Confirm data minimization practices
    • Validate deletion event emission for off-chain compliance
    • Ensure no PII leakage in on-chain data

3.2 Secondary Objectives

  1. Operational Security

    • Assess admin key compromise impact
    • Evaluate emergency pause effectiveness
    • Review incident response capabilities
    • Validate monitoring and alerting requirements

  2. Performance & Scalability

    • Assess gas efficiency of operations
    • Evaluate pagination performance
    • Review batch operation limits
    • Validate storage TTL impact on long-term operations

  3. Known Issues Resolution

    • Verify three pre-identified HIGH/MEDIUM findings are fixed:
      • FINDING-001: initialize() state read before auth
      • FINDING-002: revoke_attestation() missing require_issuer check
      • FINDING-003: update_expiration() missing require_issuer check

4. Known Issues & Pre-Audit Findings

4.1 Pre-Audit Security Review (March 25, 2026)

A preliminary authorization audit identified three findings that must be resolved before mainnet deployment:

FINDING-001 [MEDIUM] — initialize() State Read Before Auth

Location: src/lib.rs — initialize()
Status: Open
Severity: Medium
Description: Storage::has_admin() is called before admin.require_auth(), violating the principle that authorization must precede all state interaction.
Recommendation: Move require_auth() to the first line.

FINDING-002 [HIGH] — revoke_attestation() Missing require_issuer Check

Location: src/lib.rs — revoke_attestation()
Status: Open
Severity: High
Description: Function lacks Validation::require_issuer() check. De-registered issuers can still revoke their attestations.
Recommendation: Add Validation::require_issuer(&env, &issuer)?; after require_auth().

FINDING-003 [HIGH] — update_expiration() Missing require_issuer Check

Location: src/lib.rs — update_expiration()
Status: Open
Severity: High
Description: Function lacks Validation::require_issuer() check, inconsistent with renew_attestation(). De-registered issuers can extend expiration indefinitely.
Recommendation: Add Validation::require_issuer(&env, &issuer)?; after require_auth().

4.2 Known Limitations (Documented)

These are architectural limitations that are acceptable but should be understood:

  • Admin Key Compromise: Single point of failure; mitigated by multisig account
  • Issuer Key Compromise: No rate limiting or per-issuer caps
  • No On-Chain Claim Type Validation: Registry is informational only
  • Metadata Unverified: Free-form string, no content validation
  • Storage TTL Expiry: Entries evicted after 30 days of inactivity
  • Expiration Hook Callback Trust: Arbitrary external contract calls
  • Bridge Contract Trust: Binary (all-or-nothing), no per-bridge claim type restrictions
  • No Subject Consent: Subjects cannot reject attestations
  • Batch Pause Gap: create_attestations_batch not pause-gated

5. Audit Methodology

5.1 Code Review Approach

  1. Static Analysis

    • Line-by-line review of all public functions
    • Authorization flow verification
    • Storage access pattern analysis
    • Event emission completeness check

  2. Authorization Audit

    • Verify require_auth() placement (must be first meaningful call)
    • Confirm state reads occur after authorization
    • Validate TOCTOU (time-of-check-time-of-use) safety
    • Check admin/issuer/subject role enforcement

  3. Data Flow Analysis

    • Trace attestation creation through storage
    • Verify ID generation determinism
    • Validate pagination boundary conditions
    • Check batch operation atomicity

  4. Threat Modeling

    • Review against documented threat model
    • Identify potential attack vectors
    • Assess impact of key compromise
    • Evaluate emergency response capabilities

  5. Test Coverage Review

    • Analyze unit test completeness
    • Review integration test scenarios
    • Assess fuzz test effectiveness
    • Identify coverage gaps

5.2 Testing Approach

  1. Functional Testing

    • Execute all provided tests
    • Verify test coverage of critical paths
    • Validate test assertions

  2. Security Testing

    • Attempt authorization bypass scenarios
    • Test boundary conditions
    • Verify error handling
    • Assess state consistency under failure

  3. Integration Testing

    • Test cross-contract interactions
    • Verify event emission accuracy
    • Validate fee collection correctness
    • Test multi-sig workflows

6. Deliverables

6.1 Audit Report

A comprehensive security audit report including:

  1. Executive Summary

    • Overall risk assessment
    • Critical findings summary
    • Recommendations for mainnet deployment

  2. Detailed Findings

    • Critical issues (must fix before mainnet)
    • High-severity issues (should fix before mainnet)
    • Medium-severity issues (consider fixing)
    • Low-severity issues (informational)
    • Informational notes and best practices

  3. Authorization Review

    • Function-by-function authorization analysis
    • Role enforcement verification
    • Access control correctness assessment

  4. Data Integrity Analysis

    • ID generation verification
    • Storage safety assessment
    • Pagination correctness validation

  5. Compliance Assessment

    • GDPR compliance verification
    • Data minimization review
    • Privacy controls assessment

  6. Recommendations

    • Mainnet readiness assessment
    • Suggested improvements
    • Operational security guidance
    • Monitoring and alerting requirements

6.2 Audit Artifacts

  • Detailed findings with code references
  • Proof-of-concept exploits (if applicable)
  • Test cases demonstrating issues
  • Remediation guidance for each finding
  • Risk matrix and prioritization

6.3 Audit Badge & Certification

  • Audit completion certificate
  • Audit badge for README and website
  • Audit report publication link
  • Auditor contact information

7. Acceptance Criteria

7.1 Audit Completion Criteria

✅ Audit Scope Document Created

  • This document defines audit boundaries and objectives

✅ Reputable Firm Engaged

  • Soroban-experienced security firm with blockchain audit track record
  • Minimum 3 years of smart contract audit experience
  • References from previous blockchain projects

✅ All Critical Findings Resolved

  • All CRITICAL severity issues fixed and verified
  • All HIGH severity issues fixed or accepted with documented risk
  • Code changes tested and verified

✅ Audit Report Published

  • Full audit report published on project website
  • Executive summary available publicly
  • Detailed findings available to stakeholders

✅ README Updated

  • Audit badge/link added to README.md
  • Audit completion date documented
  • Link to full audit report provided

7.2 Pre-Mainnet Checklist

Before mainnet deployment:

  • All three pre-audit findings (FINDING-001, FINDING-002, FINDING-003) are fixed
  • Audit scope document approved by auditor
  • Auditor engaged and audit commenced
  • All critical findings resolved
  • All high findings resolved or accepted
  • Audit report completed and reviewed
  • README updated with audit badge and link
  • Audit report published publicly
  • Admin key secured (hardware wallet or multisig)
  • Deployment key differs from long-term admin key
  • Initial issuers reviewed and key management confirmed
  • Fee configuration reviewed (if enabled)
  • Bridge contracts audited (if used)
  • Incident response runbook created
  • Event monitoring and alerting configured
  • Testnet deployment and integration testing completed

8. Audit Firm Requirements

8.1 Required Qualifications

  • Soroban Experience: Minimum 2 audits of Soroban smart contracts
  • Blockchain Expertise: 5+ years of blockchain security experience
  • Smart Contract Audits: 20+ completed smart contract security audits
  • References: Verifiable references from previous blockchain projects
  • Team: Dedicated security engineers with cryptography background

8.2 Audit Timeline

  • Engagement: 2-4 weeks
  • Audit Duration: 4-6 weeks
  • Report Delivery: 1-2 weeks after audit completion
  • Total Timeline: 7-12 weeks from engagement to report publication

8.3 Audit Cost Estimate

  • Scope: ~5,000 lines of Rust code + tests
  • Estimated Cost: $50,000 - $150,000 USD
  • Factors: Firm reputation, team size, timeline urgency

9. Risk Assessment

9.1 Current Risk Level

Pre-Audit: HIGH RISK

  • Three pre-identified security findings (1 MEDIUM, 2 HIGH)
  • Requires external security audit before mainnet
  • Not suitable for production deployment with real funds

Post-Audit (Expected): MEDIUM RISK

  • Assuming all critical findings are resolved
  • Residual risks from known limitations (documented)
  • Suitable for mainnet with operational security measures

9.2 Residual Risks (Post-Audit)

  1. Admin Key Compromise (HIGH IMPACT, LOW PROBABILITY)

    • Mitigation: Use multisig account for admin
    • Mitigation: Hardware wallet for key storage
    • Mitigation: Emergency pause mechanism

  2. Issuer Key Compromise (MEDIUM IMPACT, MEDIUM PROBABILITY)

    • Mitigation: Issuer rotation capability
    • Mitigation: Revocation monitoring
    • Mitigation: Expiration renewal workflows

  3. Storage TTL Expiry (LOW IMPACT, LOW PROBABILITY)

    • Mitigation: Periodic renewal of active attestations
    • Mitigation: Monitoring for expiry events

  4. Bridge Contract Vulnerability (MEDIUM IMPACT, LOW PROBABILITY)

    • Mitigation: Audit bridge contracts before registration
    • Mitigation: Selective bridge registration

10. Post-Audit Actions

10.1 Immediate (Week 1)

  • Publish audit report on project website
  • Add audit badge to README.md
  • Create link to full audit report
  • Announce audit completion to community
  • Address any critical findings

10.2 Short-Term (Weeks 2-4)

  • Deploy to mainnet (if all critical findings resolved)
  • Monitor contract for anomalies
  • Establish incident response procedures
  • Set up event monitoring and alerting
  • Begin operational security monitoring

10.3 Long-Term (Ongoing)

  • Maintain audit report on website
  • Monitor for security updates in Soroban SDK
  • Plan periodic security reviews (annually)
  • Track and document any incidents
  • Maintain incident response runbook

11. Contact & Communication

11.1 Project Team

  • Project Lead: [Name/Contact]
  • Technical Lead: [Name/Contact]
  • Security Contact: [Name/Contact]

11.2 Audit Firm Communication

  • Primary Contact: [Auditor Name/Email]
  • Escalation Contact: [Auditor Manager/Email]
  • Report Delivery: [Expected Date]

11.3 Stakeholder Communication

  • Community: GitHub Discussions, Discord
  • Integrators: Direct email notification
  • Regulators: As required by jurisdiction

12. Appendices

12.1 Repository Structure

TrustLink/
├── src/
│   ├── lib.rs           # Main contract (40+ functions)
│   ├── types.rs         # Data structures, errors
│   ├── storage.rs       # Storage patterns, TTL
│   ├── validation.rs    # Authorization logic
│   ├── events.rs        # Event emission
│   └── test.rs          # Unit tests (30+)
├── tests/
│   ├── authorization.rs # Authorization tests
│   ├── integration_test.rs # Integration tests
│   └── id_generation_fuzz.rs # Fuzz tests
├── examples/
│   ├── kyc-token/       # Token contract example
│   └── anchor-integration/ # Anchor flow example
├── indexer/             # Off-chain indexer (out of scope)
├── sdk/typescript/      # TypeScript SDK (out of scope)
├── docs/
│   ├── security.md      # Trust hierarchy, threat model
│   ├── security-review.md # Pre-audit findings
│   ├── compliance.md    # GDPR compliance
│   ├── monitoring.md    # Event monitoring
│   └── adr/             # Architecture decisions
├── Cargo.toml           # Dependencies
├── DEPLOYMENT.md        # Deployment guide
├── README.md            # Main documentation
└── AUDIT_SCOPE.md       # This document

12.2 Key Documentation References

  • README.md - Project overview and usage
  • docs/security.md - Trust hierarchy and threat model
  • docs/security-review.md - Pre-audit findings
  • docs/compliance.md - GDPR compliance details
  • DEPLOYMENT.md - Deployment procedures
  • docs/integration-guide.md - Cross-contract patterns

12.3 Test Execution

# Run all tests
cargo test

# Run specific test
cargo test test_create_attestation

# Run with output
cargo test -- --nocapture

# Build WASM
cargo build --target wasm32-unknown-unknown --release

# Optimize
soroban contract optimize --wasm target/wasm32-unknown-unknown/release/trustlink.wasm

12.4 Deployment Commands

# Deploy to testnet
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/trustlink.wasm \
  --source ADMIN_SECRET_KEY \
  --network testnet

# Initialize
soroban contract invoke \
  --id $CONTRACT_ID \
  --source ADMIN_SECRET_KEY \
  --network testnet \
  -- initialize \
  --admin ADMIN_PUBLIC_ADDRESS

13. Document Control

Version Date Author Changes
1.0 2026-03-26 TrustLink Team Initial audit scope document

Document Status: READY FOR AUDIT FIRM ENGAGEMENT

Next Step: Identify and contact Soroban-experienced audit firm with this scope document.