Skip to content

fix: list contacts on servers that reject a bare prop-filter - #3

Open
janbaer wants to merge 3 commits into
dominik1001:mainfrom
janbaer:fix/list-contacts-propfind
Open

janbaer wants to merge 3 commits into
dominik1001:mainfrom
janbaer:fix/list-contacts-propfind

Conversation

@janbaer

@janbaer janbaer commented Aug 16, 2026

Copy link
Copy Markdown

list-contacts returns an empty array against Open-Xchange (mailbox.org), even though the address book holds contacts and list-address-books works.

fetchVCards discovers the card hrefs with an addressbook-query whose default filter is a condition-less <prop-filter name="FN"/>. Sending the same REPORT by hand against a book holding 24 cards:

filter vCards returned
none 24
<prop-filter name="FN"/> 0
<prop-filter name="FN"> + <text-match> 4
<filter/> 24

RFC 6352 reads a bare prop-filter as "every card carrying that property", so this looks like a server bug, but it is one that any tsdav-based client walks into. The href list comes back empty, the multi-get stage never runs, and the tool reports zero contacts.

This discovers the hrefs with a PROPFIND and hands them to fetchVCards as objectUrls, which takes the addressbook-multiget path and skips the filter. resolve-contact already does exactly this, which is why get-contact worked while list-contacts did not.

Verified against mailbox.org. Four unit tests added, full suite green.

One aside: this repository's default branch on GitHub is claude/beautiful-carson-4lqy46, one commit ahead of main, so I based the PR there. Let me know if you would rather have it on main.

claude and others added 2 commits July 7, 2026 15:28
Trusted publishing can only be configured on a package that already
exists on the registry, so the initial release authenticates with an
NPM_TOKEN secret. Once carddav-mcp exists on npm and a trusted publisher
is configured for this workflow, the secret and this env line can go.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJjmg9LMuvaNqbTAXQahgU
fetchVCards discovers the card hrefs with an addressbook-query whose default
filter is a condition-less <prop-filter name="FN"/>. RFC 6352 reads that as
"every card carrying an FN property", but Open-Xchange answers it with an
empty result. The collection then looks empty, the multi-get stage never
runs, and list-contacts reports zero contacts for a populated address book.
mailbox.org is one affected host.

Discover the hrefs with a PROPFIND and hand them to fetchVCards as
objectUrls, which routes the fetch through addressbook-multiget and skips the
filter entirely. PROPFIND is mandatory for a CardDAV collection, so this
works everywhere; resolve-contact already takes the same objectUrls path,
which is why get-contact kept working while list-contacts did not.
@janbaer
janbaer marked this pull request as draft August 16, 2026 15:39
PROPFIND returns the collection itself alongside its members, and that entry
was recognised by comparing paths for exact equality. Servers differ on
whether they put a trailing slash there, and it need not match the one the
caller passed in, so the collection could survive into the href list and be
requested as if it were a card. Harmless downstream, since a response without
vCard data is filtered out anyway, but it defeats the empty-collection short
circuit and it is the same trailing-slash fragility that hrefFor already
guards against elsewhere in this repo.
@janbaer

janbaer commented Aug 16, 2026

Copy link
Copy Markdown
Author

Pushed one follow-up: the self-filter compared paths for exact equality, so a collection whose own href carries a trailing slash the caller did not pass would survive into the href list and be requested as if it were a card. Harmless downstream, since a response without vCard data is filtered out anyway, but it defeats the empty-collection short circuit and it is the same trailing-slash fragility hrefFor already guards against elsewhere in this repo. Both sides are normalised now, with a test for the mismatch.

@janbaer
janbaer marked this pull request as ready for review August 16, 2026 15:50
@dominik1001
dominik1001 changed the base branch from claude/beautiful-carson-4lqy46 to main November 17, 2026 13:13

@dominik1001 dominik1001 left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for tracking down the Open-Xchange / mailbox.org issue. Switching to PROPFIND to find the hrefs is the right direction. A few things need fixing before this can merge; details are in the inline comments.

Not in the diff: resolve-contact still has the same bug. The PR description says resolve-contact already discovers cards via PROPFIND, but its fallback scan in src/tools/resolve-contact.ts still calls fetchVCards({ addressBook }). That is the condition-less FN addressbook-query that OX answers with zero results. On mailbox.org, a card created by another client has an OX-generated filename instead of <uid>.vcf. After this PR, list-contacts returns that card's uid, but get-contact, update-contact and delete-contact miss the direct <uid>.vcf fetch, the fallback finds nothing, and they throw Contact not found: <uid>. Please move listCardUrls into a shared module and use it in resolveContact's fallback as well (fetchVCards({ addressBook, objectUrls: await listCardUrls(...) })).

Summary of the inline comments:

  1. PROPFIND errors (401/403/404/5xx) now come back as an empty contact list instead of an error.
  2. Non-ok PROPFIND members, sub-collections and non-vCard resources go into the multiget, so one bad member fails the whole listing.
  3. The collection self-filter breaks when the two URLs are percent-encoded differently (e.g. @ vs %40).
  4. A card deleted between the PROPFIND and the multiget makes the whole call throw.
  5. listCardUrls repeats normalisation that tsdav's fetchVCards already does.
  6. The tests use relative addressBookUrls, which the real tsdav client can't handle.
  7. The release workflow change has nothing to do with this fix, and its comment points to a step that doesn't exist.

(I checked these against tsdav 2.3.0.)

addressBookUrl: string,
): Promise<string[]> {
const collection = new URL(addressBookUrl, RELATIVE_BASE);
const responses = await client.propfind({

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PROPFIND errors are now silently turned into an empty list. tsdav's propfind (davRequest) does not throw on 401/403/404/5xx. It returns a single entry whose href is the request URL, e.g. [{ href: <addressBookUrl>, ok: false, status: 404 }]. The collection self-filter below then drops it, objectUrls is [], and the tool returns [].

So a wrong or stale addressBookUrl, or expired credentials, tells the agent the address book is empty. Before this change, fetchVCards went through collectionQuery and threw Collection query failed: 404 ….

Suggestion: throw when the entry for the collection itself has ok === false, or when the response has no multistatus (raw is set).

const collectionPath = withoutTrailingSlash(collection.pathname);

return responses
.map((response) => response.href)

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Every Depth:1 member except the collection itself goes into the multiget. The old addressbook-query only returned address objects. Here, members with ok === false (e.g. a 403/404 in the multistatus), sub-collections and non-vCard resources all end up in objectUrls. The server then answers the multiget with an error for those hrefs, tsdav's collectionQuery throws on any non-ok response, and the whole list-contacts call fails because of one bad member.

Suggestion: drop entries with !response.ok, and request d:resourcetype (or d:getcontenttype) instead of d:getetag so collections and non-vCard resources can be skipped.

// raw paths would let the collection itself slip into the result and be
// requested as if it were a card.
const withoutTrailingSlash = (path: string) => path.replace(/\/+$/, "");
const collectionPath = withoutTrailingSlash(collection.pathname);

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The self-filter compares raw URL.pathname strings, so percent-encoding differences break it. Example: addressBookUrl is https://dav.mailbox.org/carddav/user@example.org/Contacts/ and OX returns the collection href as /carddav/user%40example.org/Contacts/. new URL keeps @ literal in the first pathname and %40 in the second, so they don't match. The collection href then goes into the multiget, the server rejects it, and list-contacts fails, on the very server family this PR targets.

Suggestion: run decodeURIComponent on both sides before comparing.

objectUrls.length === 0
? []
: await client.fetchVCards({
addressBook: { url: addressBookUrl },

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Race: a card deleted between the PROPFIND and the multiget fails the whole listing. The multiget returns a 404 for that one href, and tsdav's collectionQuery turns it into an exception for the entire REPORT, so the agent gets an error instead of the other contacts.

Suggestion: catch the error and retry once, or fall back to fetching the cards individually.

"A list of contacts, each containing `uid`, `fn` (formatted name), `emails`, and `phones`",
} as const;

/** Lets us normalise relative collection URLs without a real origin. */

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplification: tsdav's fetchVCards already normalises objectUrls (tsdav.mjs ~683–692). It resolves relative hrefs against addressBook.url, drops the collection via urlEquals (which tolerates a trailing slash) and maps to pathname. It also skips the multiget when the list is empty.

That makes RELATIVE_BASE, withoutTrailingSlash, the pathname mapping and the objectUrls.length === 0 ternary below redundant. Something like fetchVCards({ addressBook: { url }, objectUrls: responses.filter(r => r.ok).map(r => r.href ?? '') }) would do. Only the ok/resource-type filtering is really needed here (plus the percent-encoding fix if you keep a self-filter).

};

// Caller passes the collection without the trailing slash the server uses.
await run(mockClient, "/dav/contacts");

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These tests use relative addressBookUrls (/dav/contacts, /dav/contacts/, also the default in run()), which can't work in production. The real fetchVCards does new URL(path, addressBook.url), which throws TypeError: Invalid URL for a relative base. This test only passes because fetchVCards is mocked, and RELATIVE_BASE exists only to support it.

Please use absolute URLs, like the ones list-address-books returns.

# NPM_TOKEN authenticates the first publish, before the package exists
# on the registry. Once it does, configure npm trusted publishing for
# this workflow, remove the secret, and drop the NPM_TOKEN line (OIDC
# needs npm >= 11.5.1, hence the npm upgrade step above semantic-release

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment refers to "the npm upgrade step above semantic-release", but the workflow has no such step. Whoever later switches to OIDC trusted publishing would keep the runner's bundled npm (below 11.5.1), and publishing would fail. Please reword it to something like "add a step that upgrades npm to >= 11.5.1".

Also, the NPM_TOKEN change has nothing to do with the list-contacts fix. Could you move it into its own PR?

dominik1001 added a commit that referenced this pull request Nov 18, 2026
…enames (#8)

* test: smoke-test unreadable address books and cards under foreign filenames

list-contacts must report an error when the address book cannot be read,
not an empty list that tells the agent there are no contacts. PR #3 would
have regressed this without any test noticing.

Cards written by other clients need not live at <uid>.vcf. Seed one under
an unrelated filename over CardDAV and drive get/update/delete by uid, so
resolveContact's address-book scan runs end to end and updates are checked
to land on the card's own href.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: seed the foreign smoke card with fetch instead of tsdav

Under tsx on Node 22 (CI), importing tsdav's named exports from the smoke
script fails: "The requested module 'tsdav' does not provide an export
named 'DAVClient'". The seed only needs PUT, GET and DELETE, so plain fetch
with Basic auth does it without depending on how tsx loads tsdav's bundle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@dominik1001

Copy link
Copy Markdown
Owner

Heads-up: main now has two more checks in the smoke test (#8), which CI runs against Radicale on every PR:

  1. Missing address book → tool error. list-contacts with an address book URL that doesn't exist must return isError, not []. This PR currently fails that check: I ran the new smoke test against e18b02e and got expected a tool error, got result: []. That's the first inline comment above (the PROPFIND 404 gets filtered out like the collection's own entry).
  2. Card not stored as <uid>.vcf. The test PUTs a card under an unrelated filename and then runs get-contact, update-contact and delete-contact on it by uid. This covers resolveContact's fallback scan, which this PR needs to switch to PROPFIND as well (see the review summary).

Please merge or rebase onto main so CI picks up the new checks. You can also run them locally with npm run smoke against any CardDAV server.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants