diff --git a/SUMMARY.md b/SUMMARY.md index 3b25a51..382e5d4 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -36,6 +36,8 @@ * [Deep Dives](deep-dives/README.md) * [GitHub Repo](https://github.com/vcon-dev/vcon) * [vCon IETF Working Group](https://datatracker.ietf.org/group/vcon/about/) + * [Content Integrity](deep-dives/content-integrity.md) + * [Privacy Management](deep-dives/privacy-first-conversation-management.md) * [vCon Lifecycle Management using SCITT](deep-dives/vcon-lifecycle-management-using-scitt.md) * [vCon Consent Attachment](https://claude.ai/public/artifacts/f62b38a6-8ab3-45c9-a4b2-ff9b5c756799) * [Privacy-First Conversation Management](deep-dives/privacy-first-conversation-management.md) diff --git a/deep-dives/content-integrity.md b/deep-dives/content-integrity.md new file mode 100644 index 0000000..96ee0cd --- /dev/null +++ b/deep-dives/content-integrity.md @@ -0,0 +1,26 @@ +# Content Integrity in vCon 0.3.0 + +## Overview +Content integrity is a core feature of vCon 0.3.0, providing cryptographic verification of conversation content. + +## Implementation Details + +### Content Hashing +```python +# Calculate hash for dialog content +dialog.calculate_content_hash() + +# Verify content integrity +is_valid = dialog.verify_content_hash() +``` + +### Automatic Hash Calculation +Content hashes are automatically calculated when: +- Adding external files +- Modifying dialog content +- Updating party information + +## Best Practices +- Always verify content hashes when loading external content +- Enable automatic hash calculation +- Implement hash verification in your workflow \ No newline at end of file diff --git a/vcon-library/cheat-sheet.md b/vcon-library/cheat-sheet.md index 7c5b91f..b87380d 100644 --- a/vcon-library/cheat-sheet.md +++ b/vcon-library/cheat-sheet.md @@ -10,6 +10,7 @@ icon: scroll from vcon import Vcon from vcon.party import Party from vcon.dialog import Dialog +from vcon.civic_address import CivicAddress ``` #### Creating vCons @@ -40,20 +41,37 @@ dict_data = vcon.to_dict() #### Creating & Adding Parties ```python -# Create party +# Create party with new fields party = Party( tel="+1234567890", name="John Doe", mailto="john@example.com", role="customer", + sip="sip:john@example.com", + did="did:example:123", + jCard="...", # RFC 7095 format + timezone="America/New_York", meta={"custom": "data"} ) -# Add to vCon -vcon.add_party(party) +# Add civic address +address = CivicAddress( + country="US", + a1="California", # State + a2="San Francisco", # County + a3="San Francisco", # City + pc="94105", # Postal code + sts="Market", # Street + hno="123", # House number + flr="4" # Floor +) +party.civic_address = address -# Find party -index = vcon.find_party_index("name", "John Doe") +# Party history events +party.add_event("join", "2025-08-15T10:00:00Z") +party.add_event("hold", "2025-08-15T10:05:00Z") +party.add_event("unhold", "2025-08-15T10:07:00Z") +events = party.get_events() ``` ### Dialog @@ -61,8 +79,19 @@ index = vcon.find_party_index("name", "John Doe") #### Supported MIME Types * Text: `text/plain` -* Audio: `audio/x-wav`, `audio/wav`, `audio/mpeg`, `audio/mp3`, `audio/ogg`, `audio/webm` -* Video: `video/x-mp4`, `video/ogg` +* Audio: + * `audio/x-wav`, `audio/wav` + * `audio/mpeg`, `audio/mp3`, `audio/x-mp3` + * `audio/ogg`, `audio/webm`, `audio/x-mp4` + * `audio/aac` +* Video: + * `video/mp4`, `video/webm` + * `video/x-avi`, `video/x-matroska` + * `video/quicktime`, `video/x-flv` + * `video/3gpp` +* Images: `image/jpeg`, `image/tiff` +* Documents: `application/pdf` + #### Adding Dialog @@ -197,28 +226,66 @@ uuid = Vcon.uuid8_time(custom_bits) ### Properties Reference #### Vcon Properties - * `uuid`: Unique identifier -* `vcon`: Version number +* `vcon`: Version number (0.3.0) +* `extensions`: Extension capabilities +* `must_support`: Required extensions * `created_at`: Creation timestamp * `updated_at`: Last update timestamp -* `parties`: List of participants -* `dialog`: List of dialog entries -* `attachments`: List of attachments -* `analysis`: List of analysis entries -* `redacted`: Redaction information -* `group`: Group information -* `meta`: Metadata +// ...existing code... #### Party Properties - * `tel`: Telephone number -* `stir`: STIR verification +* `sip`: SIP URI +* `did`: Decentralized Identifier +* `jCard`: vCard format contact +* `timezone`: Timezone * `mailto`: Email address * `name`: Party name * `validation`: Validation status -* `gmlpos`: Geographic position -* `civicaddress`: Civic address +* `civicaddress`: GEOPRIV compliant address * `uuid`: Unique identifier * `role`: Party role * `meta`: Additional metadata + +#### Dialog Properties +* `type`: Dialog type +* `start`: Start timestamp +* `parties`: Participant indices +* `session_id`: Session tracking +* `content_hash`: Content integrity +* `application`: Application ID +* `message_id`: Message tracking +* `disposition`: Incomplete dialog status +* `transfer_target`: Transfer destination +* `target_dialog`: Target dialog reference + +### Extensions & Features + +```python +# Add extension capability +vcon.add_extension("com.example.feature") +vcon.remove_extension("com.example.feature") +extensions = vcon.get_extensions() + +# Required extensions +vcon.add_must_support("com.example.required") +vcon.remove_must_support("com.example.required") +must_support = vcon.get_must_support() +``` + +### Dialog Disposition Values + +```python +# Create dialog with disposition +dialog = Dialog( + type="incomplete", + disposition="no-answer" # Valid values: + # - no-answer + # - congestion + # - failed + # - busy + # - hung-up + # - voicemail-no-message +) +``` \ No newline at end of file diff --git a/vcon-library/library-api.md b/vcon-library/library-api.md index f79d2f8..70e62be 100644 --- a/vcon-library/library-api.md +++ b/vcon-library/library-api.md @@ -50,6 +50,14 @@ Note: If no dictionary is provided, an empty vCon object will be created. Use `b * `add_dialog(dialog: Dialog) -> None`: Add a dialog to the vCon. * `sign(private_key: Union[rsa.RSAPrivateKey, bytes]) -> None`: Sign the vCon using JWS. * `verify(public_key: Union[rsa.RSAPublicKey, bytes]) -> bool`: Verify the JWS signature of the vCon. +* `add_extension(extension_name: str) -> None`: Adds an extension capability to the vCon. +* `remove_extension(extension_name: str) -> None`: Removes an extension capability. +* `get_extensions() -> List[str]`: Returns list of declared extensions. +* `add_must_support(feature: str) -> None`: Adds a required extension feature. +* `remove_must_support(feature: str) -> None`: Removes a required extension feature. +* `get_must_support() -> List[str]`: Returns list of required extensions. +* `calculate_content_hash() -> str`: Calculates SHA-256 hash for content integrity. +* `verify_content_hash() -> bool`: Verifies content integrity using stored hash. #### Properties @@ -152,6 +160,9 @@ Note: Optional parameters that are set to None will not create attributes on the * `is_email() -> bool`: Checks if the dialog is an email dialog. * `is_external_data_changed() -> bool`: Checks if the external data dialog's contents have changed. * `to_inline_data() -> None`: Converts the dialog from an external data dialog to an inline data dialog. +* `calculate_content_hash() -> str`: Calculates SHA-256 hash for dialog content. +* `verify_content_hash() -> bool`: Verifies dialog content integrity. +* `is_content_changed() -> bool`: Checks if content has been modified since last hash. #### Example Usage @@ -208,6 +219,9 @@ Note: Optional parameters that are set to None will not create attributes on the #### Methods * `to_dict() -> dict`: Returns a dictionary representation of the Party object. +* `add_event(event: str, timestamp: str) -> None`: Adds a party history event (join, drop, hold, unhold, mute, unmute). +* `get_events() -> List[dict]`: Returns list of party history events. +* `validate_events() -> Tuple[bool, List[str]]`: Validates party history events. #### Example Usage diff --git a/vcon-library/quickstart.md b/vcon-library/quickstart.md index ea7496d..6f6e197 100644 --- a/vcon-library/quickstart.md +++ b/vcon-library/quickstart.md @@ -24,6 +24,7 @@ from vcon import Vcon from vcon.party import Party from vcon.dialog import Dialog from vcon.party import PartyHistory +from vcon.civic_address import CivicAddress ``` ### Step 2: Create a New vCon Object @@ -209,6 +210,45 @@ if __name__ == "__main__": main() ``` +### Extensions and Required Features + +```python +# Declare extension capabilities +vcon.add_extension("com.example.feature") +vcon.add_must_support("com.example.required") + +# Check extension support +extensions = vcon.get_extensions() +required = vcon.get_must_support() +``` + +### Enhanced Party Information + +```python +# Create party with new contact methods +party = Party( + tel="+1234567890", + sip="sip:user@example.com", + did="did:example:123", + jCard="...", # RFC 7095 format + timezone="America/New_York" +) + +# Add GEOPRIV-compliant address +address = CivicAddress( + country="US", + a1="California", # State + a2="San Francisco", # County + sts="Market", # Street + hno="123" # House number +) +party.civic_address = address + +# Track party events +party.add_event("join", "2025-08-15T10:00:00Z") +party.add_event("mute", "2025-08-15T10:05:00Z") +``` + ## ### Contributing