# CommuniGate Pro Delegate Rights and Event Management

## Overview
This document describes the delegate rights system in CommuniGate Pro and how RMP v2.0 uses it for cross-account calendar management and event modification.

## Key Discoveries (2025-09-01)

### 1. Calendar Delegate Rights

#### The Problem
- Direct calendar writes to other users' calendars require explicit delegate rights
- Without delegate rights, cross-account calendar operations fail silently
- CommuniGate Pro uses mailbox-level ACL (Access Control Lists) for calendar permissions

#### The Solution: SETMAILBOXACL Command

**Correct Command Format:**
```bash
SETMAILBOXACL "user@domain" MAILBOX Calendar {delegateuser=lrswipkxtea;}
```

**Important Notes:**
- Use `SETMAILBOXACL`, NOT `SETACCOUNTACCESS` (which is for account-level access)
- Dictionary format is CommuniGate Pro format: `{key=value;}` NOT JSON format
- Calendar mailbox must exist before granting ACL rights

**ACL Rights Characters:**
- `l` - List (see the mailbox exists)
- `r` - Read (read calendar entries)
- `s` - Seen flag (mark items as seen)
- `w` - Write flag (modify flags)
- `i` - Insert (add new calendar entries)
- `p` - Post (post to calendar)
- `k` - Create mailboxes (create sub-calendars)
- `x` - Delete mailbox (remove the calendar)
- `t` - Delete messages (remove calendar entries)
- `e` - Expunge (permanently remove deleted items)
- `a` - Administer (manage ACL rights)

### 2. The all_events Organizer Pattern

#### Concept
Use a system account (`all_events@domain`) as the universal event organizer to:
- Centralize all events in one calendar for visibility
- Minimize delegate rights complexity (only all_events needs rights to other calendars)
- Enable any authorized user to modify events they created

#### Implementation

**Creating the all_events Account:**
```typescript
// Ensure all_events account exists
const allEventsEmail = `all_events@${domain}`;
const cliCommand = `CREATEACCOUNT "${allEventsEmail}" {Password="secure-password";}`;
await XIMSSService.executeCLI(session, cliCommand);

// Create Calendar mailbox
await XIMSSService.executeCLI(session, `CREATEMAILBOX "${allEventsEmail}" "Calendar"`);
await XIMSSService.executeCLI(session, `SETMAILBOXCLASS "${allEventsEmail}" "Calendar" "IPF.Appointment"`);
```

**Granting Delegate Rights Before Event Creation:**
```typescript
// Grant all_events delegate rights to resource calendars
for (const resource of resources) {
    const aclDict = `{all_events@${domain}=lrswipkxtea;}`;
    const cmd = `SETMAILBOXACL "${resource}" MAILBOX Calendar ${aclDict}`;
    await XIMSSService.executeCLI(session, cmd);
}
```

### 3. Event Creation with all_events as Organizer

**Event Structure with Custom Properties:**
```xml
<iCalendar xmlns="urn:ietf:params:xml:ns:xcal">
<vCalendar method="PUBLISH" prodid="RMP v2.0" version="2.0">
<vevent>
<uid>RMP-1756749462059-j68o9onqg</uid>
<summary>Meeting Title</summary>
<dtstart>20250901T140000</dtstart>
<dtend>20250901T150000</dtend>
<organizer CN="System Calendar">MAILTO:all_events@domain</organizer>
<attendee partstat="ACCEPTED" role="NON-PARTICIPANT" cutype="RESOURCE">MAILTO:resource@domain</attendee>
<attendee partstat="NEEDS-ACTION" role="REQ-PARTICIPANT" cutype="INDIVIDUAL">MAILTO:user@domain</attendee>
<X-RMP-ACTUAL-ORGANIZER>actualuser@domain</X-RMP-ACTUAL-ORGANIZER>
<X-RMP-BOOKING-ID>RMP-1756749462059-j68o9onqg</X-RMP-BOOKING-ID>
<X-RMP-MEETING-ID>MTG-1756749462059-xyz123</X-RMP-MEETING-ID>
</vevent>
</vCalendar>
</iCalendar>
```

**Key Points:**
- `organizer` is always `all_events@domain` for central visibility
- `X-RMP-ACTUAL-ORGANIZER` stores the real user who created the event
- Custom properties track booking and meeting IDs for RMP

### 4. Mixed Mode Booking Service

#### Resource Handling (ALWAYS Direct Write)
```typescript
// Resources MUST always have direct write without confirmation
if (email.includes('.resources.')) {
    // Grant delegate rights
    await grantDelegateRights(session, resource, 'all_events@domain');
    
    // Write directly to resource calendar
    await writeToResourceCalendar(session, eventData, resource);
}
```

#### User Handling (Mode-Dependent)
```typescript
if (invitationMode === 'direct') {
    // Direct write mode - grant delegate rights and write
    await grantDelegateRights(session, user, 'all_events@domain');
    await writeToUserCalendar(session, eventData, user);
} else {
    // Normal mode - send invitations
    await sendInvitation(session, eventData, user);
}
```

### 5. Event Modification Service

#### Permission Checking
Users can modify events if they are:
1. The actual organizer (stored in `X-RMP-ACTUAL-ORGANIZER`)
2. A domain administrator
3. Have delegate rights to the calendar

```typescript
static async canUserModifyEvent(
    session: XIMSSSession,
    eventId: string,
    userEmail: string
): Promise<{ canModify: boolean; reason?: string; actualOrganizer?: string }> {
    // Find event in all_events calendar
    const event = await findEvent(session, eventId);
    
    // Check if user is the actual organizer
    const actualOrganizer = event['X-RMP-ACTUAL-ORGANIZER'];
    if (actualOrganizer === userEmail) {
        return { canModify: true, actualOrganizer };
    }
    
    // Check if user is domain admin
    if (await isDomainAdmin(session, userEmail)) {
        return { canModify: true, reason: 'Domain administrator' };
    }
    
    // Check delegate rights
    if (await hasDelegateRights(session, 'all_events@domain', userEmail)) {
        return { canModify: true, reason: 'Has delegate rights' };
    }
    
    return { canModify: false, reason: 'Not authorized' };
}
```

#### Update Process
1. Check permissions
2. Find event in all_events calendar
3. Update event in all participant calendars
4. Maintain audit trail with custom properties

### 6. Calendar Locking During Planning

**Critical Requirement:** Keep calendars open during event planning to prevent race conditions

```typescript
// Open all participant calendars at start of planning
const handles = [];
for (const participant of allParticipants) {
    const handle = await XIMSSService.openCalendar(session, `~${participant}/Calendar`);
    handles.push({ participant, handle });
}

// Perform all planning operations...
// Check conflicts, find time slots, etc.

// Write events to all calendars

// Only close calendars after all operations complete
for (const { handle } of handles) {
    await XIMSSService.closeCalendar(session, handle);
}
```

## Best Practices

### 1. Always Check/Create Calendar Mailboxes
```typescript
// Before granting ACL rights, ensure Calendar exists
const createCmd = `CREATEMAILBOX "${userEmail}" "Calendar"`;
await XIMSSService.executeCLI(session, createCmd);

const setClassCmd = `SETMAILBOXCLASS "${userEmail}" "Calendar" "IPF.Appointment"`;
await XIMSSService.executeCLI(session, setClassCmd);
```

### 2. Use Tilde Prefix for Cross-Account Access
```typescript
// Admin accessing another user's calendar
const calendarPath = `~${userEmail}/Calendar`;
await XIMSSService.openCalendar(session, calendarPath);
```

### 3. Handle Resources Specially
- Resources are regular CommuniGate Pro accounts in subdomain structure
- Pattern: `resource@type.resources.domain`
- ALWAYS write directly to resource calendars (no invitations)
- ALWAYS set `partstat="ACCEPTED"` for resources

### 4. Maintain Audit Trail
Use custom X- properties to track:
- Actual organizer
- Modification history
- Last modified by
- Creation metadata

## Troubleshooting

### Common Issues

#### "unknown command" error
- **Cause**: Using wrong command (e.g., SETACCOUNTACCESS instead of SETMAILBOXACL)
- **Solution**: Use correct mailbox-level commands

#### "mailbox does not exist" error
- **Cause**: Calendar mailbox not created
- **Solution**: Create mailbox before granting ACL rights

#### "no '=' after a key" error
- **Cause**: Using JSON format instead of CommuniGate dictionary format
- **Solution**: Use `{key=value;}` format

#### Events not appearing in calendars
- **Cause**: Missing delegate rights
- **Solution**: Grant delegate rights before writing to calendars

#### Session timeout (HTTP 550) errors
- **Cause**: Long-running operations without session refresh
- **Solution**: Implement session keep-alive or connection pooling

## API Endpoints

### Event Modification Endpoints

**Update Event:**
```http
PUT /api/v2/bookings/:bookingId
Authorization: Bearer {token}
Content-Type: application/json

{
    "title": "Updated Title",
    "description": "Updated description",
    "start": "2025-09-01T14:00:00Z",
    "end": "2025-09-01T15:00:00Z",
    "attendees": ["user1@domain", "user2@domain"],
    "resources": ["room@type.resources.domain"]
}
```

**Cancel Event:**
```http
DELETE /api/v2/bookings/:bookingId
Authorization: Bearer {token}
Content-Type: application/json

{
    "reason": "Meeting canceled due to schedule conflict"
}
```

## References

- CommuniGate Pro XIMSS Protocol Documentation
- CommuniGate Pro CLI Commands Reference
- RMP v2.0 Service Documentation
- Calendar Publishing Fix Documentation (2025-01-24)

## Change Log

- **2025-09-01**: Initial documentation of delegate rights and event management
- **2025-09-01**: Added all_events organizer pattern
- **2025-09-01**: Documented EventUpdateService implementation
- **2025-09-01**: Added troubleshooting section for common issues