CardDAV (Contacts Sync)

bext can serve as a CardDAV server (RFC 6352), enabling contacts synchronization with standards-compliant clients — Apple Contacts, Thunderbird, GNOME Contacts, DAVx5, and others. It shares the same WebDAV foundation and storage backend as CalDAV.

Enabling CardDAV

CardDAV is enabled through the same [caldav] config section, since both protocols share the WebDAV stack and storage:

[caldav]
enabled = true
storage = "memory"   # "memory" | "pg"

# For PostgreSQL storage
# storage = "pg"
# pg_url = "postgresql://user:pass@localhost/bext_dav"

Compile with the caldav feature flag:

bext build --features caldav

When [caldav] is enabled, both CalDAV and CardDAV endpoints are active.

WebDAV Foundation

CardDAV uses the same WebDAV methods as CalDAV:

URL Structure

Address book collections follow a predictable hierarchy:

/addressbooks/{user}/                       # User's address book home
/addressbooks/{user}/{book}/                # A specific address book
/addressbooks/{user}/{book}/{uid}.vcf       # A single contact

Example:

/addressbooks/alice/contacts/
/addressbooks/alice/contacts/bob-smith.vcf
/addressbooks/alice/team/

vCard Format

Contacts are stored as vCard 4.0 (RFC 6350) .vcf files. bext parses and validates them on PUT:

BEGIN:VCARD
VERSION:4.0
FN:Bob Smith
N:Smith;Bob;;;
EMAIL;TYPE=work:bob@example.com
TEL;TYPE=cell:+1-555-0123
ADR;TYPE=home:;;123 Main St;Springfield;IL;62701;US
ORG:Acme Corp
END:VCARD

Supported vCard properties include:

CardDAV Reports

Clients query address books using REPORT requests. bext supports three report types:

addressbook-query

Search contacts by property value:

<card:addressbook-query xmlns:card="urn:ietf:params:xml:ns:carddav">
  <d:prop xmlns:d="DAV:">
    <d:getetag/>
    <card:address-data/>
  </d:prop>
  <card:filter>
    <card:prop-filter name="EMAIL">
      <card:text-match collation="i;unicode-casemap"
                       match-type="contains">example.com</card:text-match>
    </card:prop-filter>
  </card:filter>
</card:addressbook-query>

addressbook-multiget

Fetch specific contacts by URL in a single request:

<card:addressbook-multiget xmlns:card="urn:ietf:params:xml:ns:carddav">
  <d:prop xmlns:d="DAV:">
    <d:getetag/>
    <card:address-data/>
  </d:prop>
  <d:href>/addressbooks/alice/contacts/bob-smith.vcf</d:href>
  <d:href>/addressbooks/alice/contacts/carol-jones.vcf</d:href>
</card:addressbook-multiget>

sync-collection

Efficient incremental sync (RFC 6578), identical to CalDAV's sync mechanism. The client sends a sync token and receives only changes:

<d:sync-collection xmlns:d="DAV:">
  <d:sync-token>data:,67890</d:sync-token>
  <d:prop>
    <d:getetag/>
  </d:prop>
</d:sync-collection>

Discovery

Clients discover CardDAV using the .well-known redirect (RFC 6764):

GET /.well-known/carddav
→ 301 /addressbooks/

bext registers this redirect automatically when CardDAV is enabled. Client apps only need the server hostname to find the address book home.

Shared Storage Backend

CardDAV shares its storage backend with CalDAV — both use the [caldav] config section and the same database tables. See the CalDAV docs for storage backend details.

Authentication

CardDAV endpoints require authentication, using the same middleware as all other bext routes:

[[routes]]
path = "/addressbooks/*"
auth = "required"

The {user} in the URL path is matched against the authenticated identity. Users can only access their own address books unless granted explicit sharing permissions.

Configuration

CardDAV uses the [caldav] configuration section. Contact-specific limits:

[caldav]
enabled = true
storage = "pg"
pg_url = "postgresql://user:pass@localhost/bext_dav"
max_contact_size_bytes = 65536
max_contacts_per_book = 100000

Feature Flag

CardDAV requires the caldav feature flag (shared with CalDAV):

bext build --features caldav

Related

- CalDAV (Calendar Sync) — companion protocol sharing the same WebDAV stack and storage backend

- Auth capability — authentication middleware applied to /addressbooks/* routes

- Build flags — compile-time feature flags; caldav enables both CalDAV and CardDAV

- Configuration reference — full bext.config.toml field reference

Links

- RFC 6352 — CardDAV: vCard Extensions to WebDAV — the CardDAV protocol specification

- RFC 6350 — vCard Format Specification — the vCard 4.0 format used for .vcf contact files