ciaf-core 0.1.1__tar.gz

ciaf_core-0.1.1/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to the CIAF Core package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-21
+
+### Added
+
+#### Core Package Structure
+- Initial package structure with `ciaf_core` namespace
+- Package configuration with `pyproject.toml`
+- Business Source License 1.1 (converts to Apache 2.0 on January 1, 2029)
+- Comprehensive README and QUICKSTART documentation
+
+#### Schema Models
+- `CIAFEvent` - Canonical event schema
+- `Actor` - Entity performing actions
+- `Subject` - Target of actions
+- `Resource` - Resources involved in actions
+- `Action` - Action performed and outcome
+- `PolicyDecision` - Policy evaluation results
+- `RiskAssessment` - Risk analysis records
+- `ExecutionContext` - Runtime environment information
+- `EvidenceRecord` - Cryptographic evidence tracking
+- `LineageInfo` - Provenance and lineage tracking
+- `GovernanceMapping` - Compliance framework mappings
+- `Relationship` - Entity relationships
+- `SignedEvent` - Cryptographically signed event envelope for authentication and integrity
+
+#### Enumerations
+- `ActorType` - Types of actors (human, agent, service, model, system)
+- `SubjectType` - Types of subjects (agent, model, dataset, workflow, policy, etc.)
+- `ResourceType` - Types of resources
+- `ActionType` - Types of actions (read, write, execute, deploy, etc.)
+- `ActionOutcome` - Action outcomes (success, blocked, failed, partial, pending)
+- `EventCategory` - Event categories (execution, governance, deployment, etc.)
+- `RiskLevel` - Risk levels (critical, high, medium, low, minimal, none)
+- `PolicyEffect` - Policy effects (allow, deny, require_approval, etc.)
+- `EvidenceType` - Evidence types
+- `LineageType` - Lineage relationship types
+- `RelationshipType` - Entity relationship types
+
+#### Utilities
+
+**Canonicalization** (`ciaf_core.canonicalization`)
+- `to_canonical_dict()` - Convert models to canonical dictionaries
+- `to_canonical_json()` - Deterministic JSON serialization
+- `dict_to_canonical_json()` - Dictionary canonicalization
+
+**Hashing** (`ciaf_core.hashing`)
+- `sha256_hex()` - SHA-256 hashing (hex output)
+- `sha256_bytes()` - SHA-256 hashing (bytes output)
+- `sha512_hex()` - SHA-512 hashing
+- `blake2b_hex()` - BLAKE2b hashing
+- `compute_merkle_leaf()` - Merkle tree leaf hash
+- `compute_merkle_node()` - Merkle tree node hash
+
+**ID Generation** (`ciaf_core.IDs`)
+- `new_event_id()` - Event ID generation
+- `new_entity_id()` - Entity ID generation
+- `new_uuid()` - UUID v4 generation
+- `new_ulid()` - ULID-like ID generation
+- `new_short_id()` - Short random IDs
+- `new_correlation_id()` - Correlation IDs for tracing
+- `new_decision_id()` - Policy decision IDs
+- `new_assessment_id()` - Risk assessment IDs
+
+**Validation Helpers** (`ciaf_core.validation_helpers`)
+- `validate_model()` - Pydantic model validation
+- `validate_event_id()` - Event ID format validation
+- `validate_hash()` - Hash string validation
+- `validate_tenant_id()` - Tenant ID validation
+- `is_valid_schema_version()` - Semantic version validation
+- `validate_json_dict()` - JSON dictionary validation
+- `validate_required_fields()` - Required field checking
+- `sanitize_string()` - String sanitization
+- `ensure_dict_keys_valid()` - Dictionary key validation
+
+**Signing** (`ciaf_core.signing`)
+- `generate_rsa_keypair()` - Generate RSA key pairs (2048, 3072, or 4096 bit)
+- `generate_ed25519_keypair()` - Generate Ed25519 key pairs (recommended)
+- `generate_ecdsa_keypair()` - Generate ECDSA P-256 key pairs
+- `sign_payload()` - Sign a payload with a private key
+- `verify_signature()` - Verify a signature with a public key
+- `compute_payload_hash()` - Compute SHA-256 hash of payload
+- Support for Ed25519, RSA-PSS-SHA256, and ECDSA-P256-SHA256 algorithms
+
+**Builders** (`ciaf_core.builders`)
+- `build_agent_tool_call_event()` - Agent tool call events
+- `build_model_deployment_event()` - Model deployment events
+- `build_policy_decision_event()` - Policy decision events
+- `build_evidence_record()` - Evidence records
+- `build_access_event()` - Resource access events
+
+#### Exceptions
+- `CIAFError` - Base exception
+- `CIAFValidationError` - Validation errors
+- `CIAFSchemaError` - Schema errors
+- `CIAFHashError` - Hashing errors
+- `CIAFCanonializationError` - Canonicalization errors
+- `CIAFIDGenerationError` - ID generation errors
+- `CIAFSigningError` - Signing operation errors
+- `CIAFVerificationError` - Signature verification errors
+
+#### Testing
+- Comprehensive test suite with pytest
+- Tests for event models
+- Tests for canonicalization
+- Tests for hashing utilities
+- Tests for ID generation
+- Tests for builders
+- Tests for validation helpers
+- Test fixtures and utilities
+
+#### Documentation
+- README.md with overview and features
+- QUICKSTART.md with usage examples
+- CHANGELOG.md with release notes
+- Example script (`example_signed_event.py`)
+- Inline code documentation and type hints
+
+### Technical Details
+- Python 3.11+ support
+- Pydantic v2 for data validation
+- Deterministic JSON serialization for cryptographic consistency
+- Schema version 1.0.0 embedded in all events
+
+[0.1.0]: https://github.com/your-org/ciaf_core/releases/tag/v0.1.0

ciaf_core-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,287 @@
+# Contributing to CIAF Core
+
+Thank you for your interest in contributing to CIAF Core! This document provides guidelines for developers.
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11 or higher
+- Git
+- pip
+
+### Initial Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/DenzilGreenwood/ciaf_core.git
+   cd ciaf_core
+   ```
+
+2. **Create a virtual environment:**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install development dependencies:**
+   ```bash
+   pip install -e .[dev]
+   ```
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -p no:asyncio
+
+# Run with coverage
+pytest tests/ -p no:asyncio --cov=ciaf_core --cov-report=html
+
+# Run specific test file
+pytest tests/test_signing.py -p no:asyncio -v
+```
+
+### Code Quality
+
+```bash
+# Format code with black
+black ciaf_core tests
+
+# Lint with ruff
+ruff check ciaf_core tests
+```
+
+### Building the Package
+
+```bash
+# Clean previous builds
+Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
+
+# Build distribution
+python -m build
+
+# Verify package
+python -m twine check dist/*
+```
+
+## Code Guidelines
+
+### Python Style
+
+- Follow PEP 8 style guidelines
+- Use type hints for all function parameters and return values
+- Document all public APIs with docstrings
+- Keep line length to 100 characters (configured in pyproject.toml)
+
+### Schema Design
+
+When adding or modifying schemas:
+
+1. **Backward Compatibility**: Ensure changes don't break existing code
+2. **Validation**: Use Pydantic validators for data integrity
+3. **Documentation**: Add clear docstrings explaining the schema purpose
+4. **Tests**: Include comprehensive tests for new schemas
+
+Example:
+```python
+from pydantic import BaseModel, Field, ConfigDict
+
+class MySchema(BaseModel):
+    """
+    Brief description of what this schema represents.
+    
+    Used for: Explain the use case
+    """
+    
+    model_config = ConfigDict(
+        extra="forbid",
+        str_strip_whitespace=True,
+    )
+    
+    field_name: str = Field(
+        ...,
+        description="Clear description of the field",
+        min_length=1,
+    )
+```
+
+### Utility Functions
+
+- Keep functions focused on a single responsibility
+- Add error handling with custom exceptions
+- Include usage examples in docstrings
+- Write tests covering both success and error cases
+
+### Enumeration Guidelines
+
+- Use descriptive names in UPPER_SNAKE_CASE
+- Provide clear enum class docstrings
+- String values should be lowercase with hyphens
+- Add new enum values only at the end (for backward compatibility)
+
+## Testing Guidelines
+
+### Test Structure
+
+```python
+def test_feature_name():
+    """Test description explaining what is being tested."""
+    # Arrange: Set up test data
+    input_data = {...}
+    
+    # Act: Execute the function
+    result = function_under_test(input_data)
+    
+    # Assert: Verify the result
+    assert result.field == expected_value
+```
+
+### Test Coverage
+
+- Aim for 90%+ code coverage
+- Test both success and failure paths
+- Include edge cases and boundary conditions
+- Test error handling and validation
+
+### Test Fixtures
+
+Use pytest fixtures for reusable test data:
+
+```python
+@pytest.fixture
+def sample_event():
+    """Fixture providing a sample CIAF event."""
+    return CIAFEvent(...)
+```
+
+## Commit Guidelines
+
+### Commit Messages
+
+Follow conventional commit format:
+
+```
+type(scope): brief description
+
+Longer explanation if needed
+
+Fixes #issue-number
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `test`: Test additions or changes
+- `refactor`: Code refactoring
+- `chore`: Build/tooling changes
+
+**Examples:**
+```
+feat(signing): add ECDSA P-256 signature support
+
+Add support for ECDSA P-256 signatures alongside Ed25519 and RSA.
+Includes key generation, signing, and verification functions.
+
+Fixes #42
+```
+
+## Pull Request Process
+
+1. **Create a branch:**
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make changes and commit:**
+   ```bash
+   git add .
+   git commit -m "feat(scope): description"
+   ```
+
+3. **Run tests and ensure they pass:**
+   ```bash
+   pytest tests/ -p no:asyncio
+   ```
+
+4. **Push to GitHub:**
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+5. **Create Pull Request:**
+   - Provide clear description of changes
+   - Reference any related issues
+   - Ensure CI/CD checks pass
+   - Wait for review
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes
+
+### Version Updates
+
+When incrementing version:
+
+1. Update `version` in `pyproject.toml`
+2. Update `CHANGELOG.md` with changes
+3. Create a git tag: `git tag v0.2.0`
+4. Push tag: `git push origin v0.2.0`
+
+## Documentation
+
+### Docstring Format
+
+Use Google-style docstrings:
+
+```python
+def my_function(param1: str, param2: int) -> bool:
+    """
+    Brief one-line description.
+    
+    Longer description explaining the function purpose,
+    behavior, and usage.
+    
+    Args:
+        param1: Description of param1
+        param2: Description of param2
+        
+    Returns:
+        Description of return value
+        
+    Raises:
+        ValueError: When validation fails
+        
+    Example:
+        >>> result = my_function("test", 42)
+        >>> assert result is True
+    """
+```
+
+### Updating Documentation
+
+When adding features:
+
+1. Update README.md with new capabilities
+2. Add examples to QUICKSTART.md
+3. Update CHANGELOG.md under "Unreleased"
+4. Create or update example scripts
+
+## License
+
+By contributing to CIAF Core, you agree that your contributions will be licensed under the Business Source License 1.1 (BUSL-1.1).
+
+## Questions?
+
+- **Repository**: https://github.com/DenzilGreenwood/ciaf_core
+- **Issues**: https://github.com/DenzilGreenwood/ciaf_core/issues
+- **Email**: Founder@CognitiveInsight.ai
+
+Thank you for contributing to CIAF Core!

ciaf_core-0.1.1/IDs/__init__.py

@@ -0,0 +1,192 @@
+"""
+ID generation and management utilities for CIAF Core.
+
+Provides functions for generating unique identifiers for events and entities.
+"""
+
+import uuid
+import secrets
+from datetime import datetime, timezone
+from ..exceptions import CIAFIDGenerationError
+
+
+def new_event_id(prefix: str = "evt") -> str:
+    """
+    Generate a new unique event ID.
+
+    Format: {prefix}_{timestamp}_{random}
+    Example: evt_20240321_abc123xyz
+
+    Args:
+        prefix: Prefix for the event ID (default: "evt")
+
+    Returns:
+        Unique event ID string
+
+    Raises:
+        CIAFIDGenerationError: If ID generation fails
+    """
+    try:
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+        random_suffix = secrets.token_hex(8)  # 16 characters
+        return f"{prefix}_{timestamp}_{random_suffix}"
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate event ID: {e}") from e
+
+
+def new_entity_id(entity_type: str, prefix: str = "") -> str:
+    """
+    Generate a new unique entity ID.
+
+    Format: {prefix}{entity_type}_{uuid}
+    Example: agent_550e8400-e29b-41d4-a716-446655440000
+
+    Args:
+        entity_type: Type of entity (e.g., "agent", "model", "policy")
+        prefix: Optional prefix (default: "")
+
+    Returns:
+        Unique entity ID string
+
+    Raises:
+        CIAFIDGenerationError: If ID generation fails
+    """
+    try:
+        unique_id = str(uuid.uuid4())
+        if prefix:
+            return f"{prefix}{entity_type}_{unique_id}"
+        return f"{entity_type}_{unique_id}"
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate entity ID: {e}") from e
+
+
+def new_uuid() -> str:
+    """
+    Generate a new UUID v4.
+
+    Returns:
+        UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+
+    Raises:
+        CIAFIDGenerationError: If UUID generation fails
+    """
+    try:
+        return str(uuid.uuid4())
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate UUID: {e}") from e
+
+
+def new_ulid() -> str:
+    """
+    Generate a new ULID (Universally Unique Lexicographically Sortable Identifier).
+
+    Note: This is a simplified implementation. For production use, consider
+    installing the 'python-ulid' package for full ULID support.
+
+    Returns:
+        ULID-like string based on timestamp and randomness
+
+    Raises:
+        CIAFIDGenerationError: If ULID generation fails
+    """
+    try:
+        # Simplified ULID: timestamp in milliseconds + random bytes
+        timestamp_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
+        random_part = secrets.token_hex(10)  # 20 characters
+        return f"{timestamp_ms:013x}{random_part}"
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate ULID: {e}") from e
+
+
+def new_short_id(length: int = 12) -> str:
+    """
+    Generate a short random ID.
+
+    Useful for correlation IDs, request IDs, etc.
+
+    Args:
+        length: Length of the ID in characters (default: 12)
+
+    Returns:
+        Random hexadecimal ID string
+
+    Raises:
+        CIAFIDGenerationError: If ID generation fails
+    """
+    try:
+        if length < 4:
+            raise ValueError("Length must be at least 4 characters")
+        byte_length = (length + 1) // 2
+        return secrets.token_hex(byte_length)[:length]
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate short ID: {e}") from e
+
+
+def new_correlation_id() -> str:
+    """
+    Generate a new correlation ID for tracing across systems.
+
+    Returns:
+        Correlation ID string
+
+    Raises:
+        CIAFIDGenerationError: If correlation ID generation fails
+    """
+    try:
+        return f"corr_{new_short_id(16)}"
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate correlation ID: {e}") from e
+
+
+def new_decision_id(prefix: str = "dec") -> str:
+    """
+    Generate a new unique decision ID.
+
+    Args:
+        prefix: Prefix for the decision ID (default: "dec")
+
+    Returns:
+        Unique decision ID string
+
+    Raises:
+        CIAFIDGenerationError: If decision ID generation fails
+    """
+    try:
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+        random_suffix = secrets.token_hex(6)  # 12 characters
+        return f"{prefix}_{timestamp}_{random_suffix}"
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate decision ID: {e}") from e
+
+
+def new_assessment_id(prefix: str = "assess") -> str:
+    """
+    Generate a new unique assessment ID.
+
+    Args:
+        prefix: Prefix for the assessment ID (default: "assess")
+
+    Returns:
+        Unique assessment ID string
+
+    Raises:
+        CIAFIDGenerationError: If assessment ID generation fails
+    """
+    try:
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+        random_suffix = secrets.token_hex(6)  # 12 characters
+        return f"{prefix}_{timestamp}_{random_suffix}"
+    except Exception as e:
+        raise CIAFIDGenerationError(f"Failed to generate assessment ID: {e}") from e
+
+
+__all__ = [
+    "new_event_id",
+    "new_entity_id",
+    "new_uuid",
+    "new_ulid",
+    "new_short_id",
+    "new_correlation_id",
+    "new_decision_id",
+    "new_assessment_id",
+]