Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
26 changes: 26 additions & 0 deletions deep-dives/content-integrity.md
Original file line number Diff line number Diff line change
@@ -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
107 changes: 87 additions & 20 deletions vcon-library/cheat-sheet.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -40,29 +41,57 @@ 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

#### 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

Expand Down Expand Up @@ -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
)
```
14 changes: 14 additions & 0 deletions vcon-library/library-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
40 changes: 40 additions & 0 deletions vcon-library/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down