# Cal.diy Connector

The Cal.diy connector projects the pinned self-hosted scheduling API into 81
typed AIP capabilities. It is built into `aipd` and is the reference product
connector for governed mutations, tenant credential routing, signed webhook
ingress, idempotency fencing, and recovery.

## What It Supports

| Capability family | Count | Examples |
|---|---:|---|
| Profile | 2 | Read and update the authenticated profile |
| Event types | 15 | CRUD, private links, and webhooks |
| Slots | 5 | Availability and reservation lifecycle |
| Bookings | 22 | Create, reschedule, cancel, attendees, recordings, and transcripts |
| Calendars | 21 | Connections, busy time, event CRUD, free/busy, and selection |
| Conferencing | 5 | List, default, connect, and disconnect |
| Schedules | 6 | List, read, create, update, and delete |
| User webhooks | 5 | Signed webhook CRUD |

Interactive OAuth callbacks, raw credential capture, deprecated routes, and
unbounded outbound URL operations are deliberately excluded.

## Configure `aipd`

Provide exactly one Cal.diy authentication mode through secret files:

```sh
cargo run -p aipd -- \
  --bind 0.0.0.0:18080 \
  --service-id agent:aipd:calendar \
  --native-bearer-token-file /run/secrets/aip-native-token \
  --native-principal service:calendar-edge \
  --native-principal-scope action:read \
  --native-principal-scope action:write \
  --trusted-identity-file /run/aip/trusted-identities.json \
  --approval-authority-file /run/aip/approval-authorities.json \
  --postgres-url "$AIP_POSTGRES_URL" \
  --cal-diy-base-url https://calendar.example.com/api \
  --cal-diy-account-id primary \
  --cal-diy-bearer-token-file /run/secrets/cal-diy-token
```

OAuth client authentication uses `--cal-diy-oauth-client-id` and
`--cal-diy-oauth-client-secret-file` instead of the bearer-token file.

For multiple tenants, bind each trusted tenant to an external account and
opaque credential handle. The trusted identity directory is authoritative;
action input cannot select another tenant's credential.

The command is a composition example, not a complete public-edge deployment.
Terminate TLS, restrict health and metrics routes, and grant only the scopes
required by the chosen capabilities.

See [`aipd` Configuration](../reference/configuration.md#caldiy-connector) for
all connector options and [Environment Variables](../reference/environment-variables.md)
for orchestrator equivalents.

## Mutation Safety

Every mutation requires an external-account-scoped idempotency key and AIP
approval. High-risk booking create, reschedule, and cancel operations require a
validated plan before commit.

Cal.diy does not provide universal provider idempotency. The connector
therefore claims a durable dispatch fence before sending a mutation and never
blindly retries an uncertain provider outcome. When provider response and
settlement evidence are both unavailable, the operation remains fenced for
operator reconciliation.

Use PostgreSQL for multi-process deployment. The file-backed runtime is a
single-host durability option, not a shared cluster coordinator.

## Signed Webhooks

Configure one secret selector per owned webhook subscription:

```text
--cal-diy-webhook-secret-file bookings=/run/secrets/cal-diy-bookings-hmac
--cal-diy-webhook-subscriber-prefix https://aip.example.com/connectors/cal-diy/webhooks/
```

The provider sends to:

```text
POST /connectors/cal-diy/webhooks/bookings
```

The connector verifies the exact raw body, required version, HMAC signature,
timestamp window, replay identity, and payload bound before appending a native
event. Provider retries resolve to the same deterministic event id.

## Qualification Boundary

The connector has complete frozen-SDK conformance and a retained
exact-upstream isolated-live report for its named source and image artifacts.
That historical report does not automatically qualify a rebuild or a new
Cal.diy revision. Run the campaign again for the exact production artifact.

For the full provider baseline and safety boundaries, read
[Pinned Upstream Baselines](upstream-baselines.md). Evidence is described in
[Cal.diy Isolated-Live Evidence](../testing/cal-diy-isolated-live.md).