'pending_materialization', so a
+// pending_materialization mapping reads as sync_state 'local', never pending_materialization.
+const PENDING_SYNC_STATES = new Set(['pending_push']);
+
+export function contactCarddavState(contact) {
+ if (!isCardDavContact(contact)) {
+ return { labelKey: null, canEdit: true, canDelete: true, conflictId: null };
+ }
+
+ const conflictId = contact.conflict_id || null;
+ if (contact.sync_state === 'conflict' || conflictId) {
+ return {
+ labelKey: 'contacts.carddavConflict',
+ canEdit: false,
+ canDelete: false,
+ conflictId,
+ };
+ }
+
+ const canEdit = contact.remote_update_capability !== 'denied';
+ const canDelete = contact.remote_delete_capability !== 'denied';
+ if (PENDING_SYNC_STATES.has(contact.sync_state)) {
+ // A distinct pending marker: the contact stays editable (a re-edit is fenced by the
+ // backend's pending-intent handling), it just is not fully synced yet.
+ return { labelKey: 'contacts.carddavPending', canEdit, canDelete, conflictId: null };
+ }
+ return {
+ labelKey: canEdit || canDelete ? 'contacts.carddavSynced' : 'contacts.carddavReadOnly',
+ canEdit,
+ canDelete,
+ conflictId: null,
+ };
+}
+
+// The detail view's avatar uploads a photo through the same update as the edit form, so it
+// is offered on exactly the contacts that update is allowed on.
+export function canUploadContactPhoto(contact) {
+ return Boolean(contact) && contactCarddavState(contact).canEdit;
+}
+
+export function cloneFields(fields) {
+ return (fields || []).map(field => ({
+ id: field?.id,
+ kind: field?.kind,
+ label: field?.label,
+ value: field?.value && typeof field.value === 'object'
+ ? { ...field.value }
+ : field?.value,
+ }));
+}
+
+export function contactToForm(contact = {}) {
+ return {
+ displayName: contact.display_name || '',
+ firstName: contact.first_name || '',
+ lastName: contact.last_name || '',
+ emails: contact.emails?.length
+ ? contact.emails.map(email => ({ ...email }))
+ : [{ value: '', type: 'other', primary: true }],
+ phones: (contact.phones || []).map(phone => ({ ...phone })),
+ organization: contact.organization || '',
+ notes: contact.notes || '',
+ photoData: contact.photo_data || null,
+ hasPhoto: Boolean(contact.has_photo || contact.photo_data),
+ additionalFields: cloneFields(contact.additional_fields),
+ carddav: {
+ syncState: contact.sync_state || 'local',
+ capabilities: {
+ create: contact.remote_create_capability || null,
+ update: contact.remote_update_capability || null,
+ delete: contact.remote_delete_capability || null,
+ },
+ conflictId: contact.conflict_id || null,
+ },
+ };
+}
+
+export function formToContactDraft(form) {
+ const displayName = form.displayName.trim()
+ || [form.firstName.trim(), form.lastName.trim()].filter(Boolean).join(' ')
+ || null;
+ return {
+ displayName,
+ firstName: form.firstName || null,
+ lastName: form.lastName || null,
+ emails: form.emails.filter(email => email.value.trim()),
+ phones: form.phones.filter(phone => phone.value.trim()),
+ organization: form.organization || null,
+ notes: form.notes || null,
+ photoData: form.photoData,
+ additionalFields: cloneFields(form.additionalFields),
+ };
+}
+
+function emptyAdditionalValue(kind) {
+ if (kind === 'postal-address') {
+ return {
+ poBox: '',
+ extendedAddress: '',
+ street: '',
+ locality: '',
+ region: '',
+ postalCode: '',
+ country: '',
+ };
+ }
+ if (kind === 'im') return { protocol: '', handle: '' };
+ if (kind === 'geo') return { latitude: '', longitude: '' };
+ return '';
+}
+
+export function newAdditionalField(kind, makeId = () => crypto.randomUUID()) {
+ return {
+ id: makeId(),
+ kind,
+ label: '',
+ value: emptyAdditionalValue(kind),
+ };
+}
+
+export function removeContactPhoto(form) {
+ return { ...form, photoData: null, hasPhoto: false };
+}
+
+export function validateContactPhoto(file) {
+ if (!PHOTO_TYPES.has(file?.type)) return 'contacts.photo.invalidType';
+ if (file.size > MAX_PHOTO_BYTES) return 'contacts.photo.tooLarge';
+ return null;
+}
+
+export function initialPhotoReadState() {
+ return { generation: 0, pending: false };
+}
+
+export function beginPhotoRead(state) {
+ return { generation: state.generation + 1, pending: true };
+}
+
+export function invalidatePhotoRead(state) {
+ return { generation: state.generation + 1, pending: false };
+}
+
+export function completePhotoRead(state, generation) {
+ if (!state.pending || state.generation !== generation) {
+ return { state, accepted: false };
+ }
+ return {
+ state: { generation: state.generation, pending: false },
+ accepted: true,
+ };
+}
+
+export function shouldRefreshContactAfterResolution(contact, conflict) {
+ const uid = contact?.uid;
+ return Boolean(uid && [
+ conflict?.local?.contact?.uid,
+ conflict?.remote?.contact?.uid,
+ ].includes(uid));
+}
+
+// A post-write 409 whose body carries an ambiguous-write / pending-intent code: the
+// remote effect may have landed and MailFlow recovered read-only, so the client must
+// refresh state (re-GET) rather than blindly re-issue the mutation.
+const REFRESH_WRITE_CODES = new Set([
+ 'ERR_CARDDAV_AMBIGUOUS_WRITE',
+ 'ERR_CARDDAV_PENDING_INTENT',
+]);
+
+export function isRefreshableWriteError(error) {
+ return error?.status === 409 && REFRESH_WRITE_CODES.has(error?.data?.code);
+}
+
+export function saveFailureState(error, form) {
+ if (error?.status === 409 && error.conflictId) {
+ return {
+ view: 'conflict',
+ conflictId: error.conflictId,
+ form,
+ error: null,
+ };
+ }
+ if (isRefreshableWriteError(error)) {
+ // Keep the draft, signal the caller to re-GET the contact, and show honest copy —
+ // the write may have applied and reconciles on the next sync; don't re-issue it.
+ return {
+ view: 'refresh',
+ conflictId: null,
+ form,
+ error: null,
+ messageKey: 'contacts.carddavWriteUnconfirmed',
+ };
+ }
+ return {
+ view: 'form',
+ conflictId: null,
+ form,
+ error: error?.message || 'Request failed',
+ };
+}
diff --git a/frontend/src/contactCarddavState.test.js b/frontend/src/contactCarddavState.test.js
new file mode 100644
index 0000000..3c4c079
--- /dev/null
+++ b/frontend/src/contactCarddavState.test.js
@@ -0,0 +1,345 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+ ADDITIONAL_FIELD_KINDS,
+ beginPhotoRead,
+ canUploadContactPhoto,
+ completePhotoRead,
+ contactCarddavState,
+ contactToForm,
+ formToContactDraft,
+ initialPhotoReadState,
+ invalidatePhotoRead,
+ isRefreshableWriteError,
+ newAdditionalField,
+ removeContactPhoto,
+ saveFailureState,
+ shouldRefreshContactAfterResolution,
+ validateContactPhoto,
+} from './contactCarddavState.js';
+import * as contactCarddavHelpers from './contactCarddavState.js';
+import { api } from './utils/api.js';
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+
+describe('CardDAV contact state', () => {
+ it('labels writable, operation-read-only, and conflicted contacts from backend capabilities', () => {
+ assert.deepEqual(contactCarddavState({
+ sync_state: 'synced',
+ remote_update_capability: 'allowed',
+ remote_delete_capability: 'denied',
+ }), {
+ labelKey: 'contacts.carddavSynced',
+ canEdit: true,
+ canDelete: false,
+ conflictId: null,
+ });
+ assert.deepEqual(contactCarddavState({
+ sync_state: 'synced',
+ remote_update_capability: 'denied',
+ remote_delete_capability: 'denied',
+ }), {
+ labelKey: 'contacts.carddavReadOnly',
+ canEdit: false,
+ canDelete: false,
+ conflictId: null,
+ });
+ assert.deepEqual(contactCarddavState({
+ sync_state: 'conflict',
+ conflict_id: 'conflict-1',
+ remote_update_capability: 'allowed',
+ remote_delete_capability: 'allowed',
+ }), {
+ labelKey: 'contacts.carddavConflict',
+ canEdit: false,
+ canDelete: false,
+ conflictId: 'conflict-1',
+ });
+ });
+
+ it('marks a write-unconfirmed contact as pending, not fully synced, and keeps it editable', () => {
+ // pending_push is the only pending sync_state the contacts API can surface.
+ assert.deepEqual(contactCarddavState({
+ sync_state: 'pending_push',
+ remote_update_capability: 'allowed',
+ remote_delete_capability: 'allowed',
+ }), {
+ labelKey: 'contacts.carddavPending',
+ canEdit: true,
+ canDelete: true,
+ conflictId: null,
+ });
+ // A conflict still wins over pending, and a denied capability still gates the action.
+ assert.equal(contactCarddavState({ sync_state: 'pending_push', conflict_id: 'c1' }).labelKey,
+ 'contacts.carddavConflict');
+ assert.equal(contactCarddavState({
+ sync_state: 'pending_push',
+ remote_update_capability: 'denied',
+ remote_delete_capability: 'denied',
+ }).canEdit, false);
+ // A genuinely synced contact is unchanged.
+ assert.equal(contactCarddavState({ sync_state: 'synced', remote_update_capability: 'allowed' }).labelKey,
+ 'contacts.carddavSynced');
+ });
+
+ it('initializes an editable form without dropping photos or typed Additional fields', () => {
+ const contact = {
+ display_name: 'Ada Lovelace',
+ first_name: 'Ada',
+ last_name: 'Lovelace',
+ emails: [{ value: 'ada@example.test', type: 'work', primary: true }],
+ phones: [{ value: '+1 555 0100', type: 'mobile' }],
+ organization: 'Analytical Engines',
+ notes: 'First programmer',
+ photo_data: 'data:image/png;base64,AQID',
+ has_photo: true,
+ sync_state: 'synced',
+ remote_create_capability: 'allowed',
+ remote_update_capability: 'unknown',
+ remote_delete_capability: 'denied',
+ conflict_id: 'conflict-1',
+ additional_fields: [{
+ id: 'stable-site',
+ kind: 'url',
+ label: 'Portfolio',
+ value: 'https://example.test/ada',
+ vcard: {
+ group: 'item1',
+ name: 'URL',
+ parameters: { TYPE: ['work'] },
+ },
+ }],
+ };
+ const editableAdditionalFields = [{
+ id: 'stable-site',
+ kind: 'url',
+ label: 'Portfolio',
+ value: 'https://example.test/ada',
+ }];
+
+ const form = contactToForm(contact);
+ assert.equal(form.photoData, contact.photo_data);
+ assert.equal(form.hasPhoto, true);
+ assert.deepEqual(form.carddav, {
+ syncState: 'synced',
+ capabilities: { create: 'allowed', update: 'unknown', delete: 'denied' },
+ conflictId: 'conflict-1',
+ });
+ assert.deepEqual(form.additionalFields, editableAdditionalFields);
+ assert.notEqual(form.additionalFields, contact.additional_fields);
+ assert.equal(JSON.stringify(form.additionalFields).includes('vcard'), false);
+ assert.deepEqual(formToContactDraft(form), {
+ displayName: 'Ada Lovelace',
+ firstName: 'Ada',
+ lastName: 'Lovelace',
+ emails: contact.emails,
+ phones: contact.phones,
+ organization: 'Analytical Engines',
+ notes: 'First programmer',
+ photoData: contact.photo_data,
+ additionalFields: editableAdditionalFields,
+ });
+ assert.equal(JSON.stringify(formToContactDraft(form)).includes('parameters'), false);
+ });
+
+ it('supports every projected Additional-field kind and gives new fields stable IDs', () => {
+ assert.deepEqual(ADDITIONAL_FIELD_KINDS, [
+ 'postal-address', 'url', 'im', 'birthday', 'anniversary', 'date',
+ 'role', 'title', 'nickname', 'geo', 'custom-text',
+ ]);
+
+ const field = newAdditionalField('im', () => 'stable-generated-id');
+ assert.deepEqual(field, {
+ id: 'stable-generated-id',
+ kind: 'im',
+ label: '',
+ value: { protocol: '', handle: '' },
+ });
+ });
+
+ it('round-trips valid vCard date shapes through lossless text controls', () => {
+ const additionalFields = [
+ { id: 'basic', kind: 'birthday', label: 'Basic', value: '19960415' },
+ { id: 'partial', kind: 'anniversary', label: 'Partial', value: '--0415' },
+ { id: 'date-time', kind: 'date', label: 'Date-time', value: '19960415T143000Z' },
+ { id: 'text', kind: 'birthday', label: 'Text', value: 'circa 1996' },
+ ];
+
+ const form = contactToForm({ additional_fields: additionalFields });
+
+ assert.deepEqual(form.additionalFields.map(field => field.value), [
+ '19960415', '--0415', '19960415T143000Z', 'circa 1996',
+ ]);
+ assert.equal(typeof contactCarddavHelpers.additionalFieldInputType, 'function');
+ assert.deepEqual(form.additionalFields.map(field => ({
+ type: contactCarddavHelpers.additionalFieldInputType(field.kind),
+ value: field.value,
+ })), additionalFields.map(field => ({ type: 'text', value: field.value })));
+ assert.deepEqual(formToContactDraft(form).additionalFields, additionalFields);
+
+ const contactsPage = readFileSync(join(testDir, 'components', 'ContactsPage.jsx'), 'utf8');
+ assert.match(contactsPage, /type=\{additionalFieldInputType\(field\.kind\)\}/);
+ });
+
+ it('keeps contact status and actions in a wrapping in-flow header', () => {
+ const contactsPage = readFileSync(join(testDir, 'components', 'ContactsPage.jsx'), 'utf8');
+ const detail = contactsPage.slice(
+ contactsPage.indexOf('function ContactDetail'),
+ contactsPage.indexOf('function ContactForm'),
+ );
+
+ assert.match(detail, /flexWrap: 'wrap'/);
+ assert.doesNotMatch(detail, /paddingRight: 128/);
+ });
+
+ it('marks photo removal explicitly and rejects oversized or non-image uploads', () => {
+ assert.deepEqual(removeContactPhoto({
+ photoData: 'data:image/jpeg;base64,AQID',
+ hasPhoto: true,
+ displayName: 'Ada',
+ }), {
+ photoData: null,
+ hasPhoto: false,
+ displayName: 'Ada',
+ });
+ assert.equal(validateContactPhoto({ type: 'image/png', size: 512 * 1024 }), null);
+ assert.equal(validateContactPhoto({ type: 'image/svg+xml', size: 100 }), 'contacts.photo.invalidType');
+ assert.equal(validateContactPhoto({ type: 'image/jpeg', size: 512 * 1024 + 1 }), 'contacts.photo.tooLarge');
+ });
+
+ it('offers the detail-view photo upload only where the remote accepts an update', () => {
+ assert.equal(canUploadContactPhoto({ id: 1 }), true);
+ assert.equal(canUploadContactPhoto({
+ sync_state: 'synced',
+ remote_update_capability: 'allowed',
+ remote_delete_capability: 'denied',
+ }), true);
+ assert.equal(canUploadContactPhoto({
+ sync_state: 'pending_push',
+ remote_update_capability: 'allowed',
+ }), true);
+ assert.equal(canUploadContactPhoto({
+ sync_state: 'synced',
+ remote_update_capability: 'denied',
+ }), false);
+ assert.equal(canUploadContactPhoto({ sync_state: 'conflict', conflict_id: 'conflict-1' }), false);
+ assert.equal(canUploadContactPhoto(null), false);
+ });
+
+ it('uploads the detail-view photo from a focusable control through the edit save path', () => {
+ const contactsPage = readFileSync(join(testDir, 'components', 'ContactsPage.jsx'), 'utf8');
+ const detail = contactsPage.slice(
+ contactsPage.indexOf('function ContactDetail'),
+ contactsPage.indexOf('function ContactForm'),
+ );
+
+ assert.match(detail, /canUploadContactPhoto\(c\)/);
+ assert.match(detail, /
]*onClick/);
+ assert.match(contactsPage, /const uploadDetailPhoto = file =>/);
+ assert.match(contactsPage, /readPhotoFile\(file, photoData => submitContact\(/);
+ });
+
+ it('keeps photo reading pending and ignores a callback after the form changes', () => {
+ const reading = beginPhotoRead(initialPhotoReadState());
+ assert.equal(reading.pending, true);
+
+ const changedForm = invalidatePhotoRead(reading);
+ assert.equal(changedForm.pending, false);
+ assert.equal(changedForm.generation, reading.generation + 1);
+ assert.deepEqual(completePhotoRead(changedForm, reading.generation), {
+ state: changedForm,
+ accepted: false,
+ });
+ });
+
+ it('accepts only the newest photo read callback', () => {
+ const first = beginPhotoRead(initialPhotoReadState());
+ const second = beginPhotoRead(first);
+
+ assert.deepEqual(completePhotoRead(second, first.generation), {
+ state: second,
+ accepted: false,
+ });
+ assert.deepEqual(completePhotoRead(second, second.generation), {
+ state: { generation: second.generation, pending: false },
+ accepted: true,
+ });
+ });
+
+ it('navigates a 409 to its conflict while retaining the exact draft object', () => {
+ const form = { displayName: 'Unsaved edit' };
+ const error = Object.assign(new Error('Request failed'), {
+ status: 409,
+ conflictId: 'conflict-1',
+ });
+
+ assert.deepEqual(saveFailureState(error, form), {
+ view: 'conflict',
+ conflictId: 'conflict-1',
+ form,
+ error: null,
+ });
+ assert.equal(saveFailureState(error, form).form, form);
+ });
+
+ it('routes a 409 ambiguous/pending write to a refresh view that keeps the draft', () => {
+ const form = { displayName: 'Unsaved edit' };
+ for (const code of ['ERR_CARDDAV_AMBIGUOUS_WRITE', 'ERR_CARDDAV_PENDING_INTENT']) {
+ const error = Object.assign(new Error('unconfirmed'), {
+ status: 409,
+ data: { error: 'unconfirmed', code, refresh: true },
+ });
+ assert.equal(isRefreshableWriteError(error), true);
+ assert.deepEqual(saveFailureState(error, form), {
+ view: 'refresh',
+ conflictId: null,
+ form,
+ error: null,
+ messageKey: 'contacts.carddavWriteUnconfirmed',
+ });
+ assert.equal(saveFailureState(error, form).form, form);
+ }
+ // A conflictId 409 still routes to conflict; other errors stay a form error.
+ const conflict = Object.assign(new Error('x'), { status: 409, conflictId: 'c1' });
+ assert.equal(isRefreshableWriteError(conflict), false);
+ assert.equal(saveFailureState(conflict, form).view, 'conflict');
+ assert.equal(saveFailureState(Object.assign(new Error('boom'), { status: 500 }), form).view, 'form');
+ });
+
+ it('refreshes only the selected contact represented by the resolved conflict', () => {
+ const conflict = {
+ local: { tombstone: true, contact: null },
+ remote: { tombstone: false, contact: { uid: 'contact-1' } },
+ };
+
+ assert.equal(shouldRefreshContactAfterResolution({ uid: 'contact-1' }, conflict), true);
+ assert.equal(shouldRefreshContactAfterResolution({ uid: 'contact-2' }, conflict), false);
+ assert.equal(shouldRefreshContactAfterResolution(null, conflict), false);
+ });
+
+ it('preserves HTTP 409 metadata needed for conflict navigation', async () => {
+ const originalFetch = globalThis.fetch;
+ globalThis.fetch = async () => ({
+ ok: false,
+ status: 409,
+ json: async () => ({ conflictId: 'conflict-1' }),
+ });
+
+ try {
+ await assert.rejects(api.updateContact('contact-1', { displayName: 'Draft' }), error => {
+ assert.equal(error.status, 409);
+ assert.equal(error.conflictId, 'conflict-1');
+ assert.deepEqual(error.data, { conflictId: 'conflict-1' });
+ return true;
+ });
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+ });
+});
diff --git a/frontend/src/contactLabels.js b/frontend/src/contactLabels.js
new file mode 100644
index 0000000..663fb35
--- /dev/null
+++ b/frontend/src/contactLabels.js
@@ -0,0 +1,57 @@
+// Apple Contacts encodes its well-known X-ABLABEL values in a sentinel wrapper
+// (`_$!!$_`), and a vCard property with no X-ABLABEL falls back to its raw TYPE
+// token (`WORK`, `HOME`). CardDAV servers hand both through verbatim, so they reach the
+// client as the label of an additional field and must be humanized for display only —
+// the stored label is what the retained vCard round-trips.
+const APPLE_LABEL = /^_\$!<(.*)>!\$_$/;
+
+// Well-known label tokens, lowercased so uppercase TYPE tokens resolve like Apple's
+// mixed-case labels, mapped onto localized copy the app already ships.
+const LOCALIZED_LABELS = new Map([
+ ['home', 'contacts.emailTypes.home'],
+ ['work', 'contacts.emailTypes.work'],
+ ['other', 'contacts.emailTypes.other'],
+ ['mobile', 'contacts.phoneTypes.mobile'],
+ ['cell', 'contacts.phoneTypes.mobile'],
+ ['iphone', 'contacts.phoneTypes.mobile'],
+ ['homepage', 'contacts.additional.types.url'],
+ ['url', 'contacts.additional.types.url'],
+ ['birthday', 'contacts.additional.types.birthday'],
+ ['anniversary', 'contacts.additional.types.anniversary'],
+ ['nickname', 'contacts.additional.types.nickname'],
+ ['role', 'contacts.additional.types.role'],
+ ['title', 'contacts.additional.types.title'],
+]);
+
+export const CONTACT_LABEL_KEYS = [...new Set(LOCALIZED_LABELS.values())];
+
+function titleCase(token) {
+ return token
+ .split(/\s+/)
+ .filter(Boolean)
+ .map(word => word[0].toUpperCase() + word.slice(1).toLowerCase())
+ .join(' ');
+}
+
+export function humanizeContactLabel(label, t) {
+ const raw = String(label ?? '').trim();
+ const inner = (APPLE_LABEL.exec(raw)?.[1] ?? raw).trim();
+ if (!inner) return '';
+ const key = LOCALIZED_LABELS.get(inner.toLowerCase());
+ return key ? t(key) : titleCase(inner);
+}
+
+export function formatContactValue(value, t) {
+ if (value === null || value === undefined || value === '') return '—';
+ if (Array.isArray(value)) return value.length ? value.map(item => formatContactValue(item, t)) : '—';
+ if (typeof value !== 'object') return String(value);
+ if (value.kind) {
+ const label = humanizeContactLabel(value.label || value.kind, t)
+ || t(`contacts.additional.types.${value.kind}`);
+ return `${label}: ${formatContactValue(value.value, t)}`;
+ }
+ return Object.values(value)
+ .filter(part => part !== null && part !== undefined && part !== '' && typeof part !== 'boolean')
+ .map(String)
+ .join(' · ') || '—';
+}
diff --git a/frontend/src/contactLabels.test.js b/frontend/src/contactLabels.test.js
new file mode 100644
index 0000000..0c2e98e
--- /dev/null
+++ b/frontend/src/contactLabels.test.js
@@ -0,0 +1,107 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { CONTACT_LABEL_KEYS, formatContactValue, humanizeContactLabel } from './contactLabels.js';
+import { contactToForm, formToContactDraft } from './contactCarddavState.js';
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+
+function valueAt(object, path) {
+ return path.split('.').reduce((value, key) => value?.[key], object);
+}
+
+function localeT(locale) {
+ const messages = JSON.parse(readFileSync(join(testDir, 'locales', `${locale}.json`), 'utf8'));
+ return key => {
+ const value = valueAt(messages, key);
+ assert.equal(typeof value, 'string', `${locale} is missing ${key}`);
+ return value;
+ };
+}
+
+const t = localeT('en');
+
+describe('contact label humanizer', () => {
+ it('humanizes the raw Apple/Nextcloud label artifacts seen in production', () => {
+ // Exactly what a Nextcloud collection of Apple-authored contacts hands the client.
+ assert.equal(humanizeContactLabel('_$!!$_', t), 'Web address');
+ assert.equal(humanizeContactLabel('WORK', t), 'Work');
+ assert.equal(humanizeContactLabel('HOME', t), 'Home');
+ });
+
+ it('resolves well-known labels case-insensitively, wrapped or bare', () => {
+ for (const label of ['work', 'Work', 'WORK', '_$!!$_', '_$!!$_']) {
+ assert.equal(humanizeContactLabel(label, t), 'Work');
+ }
+ assert.equal(humanizeContactLabel('_$!!$_', t), 'Other');
+ assert.equal(humanizeContactLabel('CELL', t), 'Mobile');
+ assert.equal(humanizeContactLabel('_$!!$_', t), 'Mobile');
+ assert.equal(humanizeContactLabel('_$!!$_', t), 'Anniversary');
+ });
+
+ it('reuses the localized copy the app already ships, in every locale', () => {
+ const de = localeT('de');
+ assert.equal(humanizeContactLabel('WORK', de), 'Arbeit');
+ assert.equal(humanizeContactLabel('_$!!$_', de), 'Webadresse');
+ const zhCN = localeT('zhCN');
+ assert.equal(humanizeContactLabel('HOME', zhCN), '家庭');
+
+ // Every mapped key must be an existing key — no parallel copy for labels.
+ const en = JSON.parse(readFileSync(join(testDir, 'locales', 'en.json'), 'utf8'));
+ const missing = CONTACT_LABEL_KEYS.filter(key => typeof valueAt(en, key) !== 'string');
+ assert.deepEqual(missing, []);
+ });
+
+ it('strips the wrapper and title-cases anything it does not know', () => {
+ assert.equal(humanizeContactLabel('_$!!$_', t), 'Fax');
+ assert.equal(humanizeContactLabel('PAGER', t), 'Pager');
+ assert.equal(humanizeContactLabel('MAIN', t), 'Main');
+ assert.equal(humanizeContactLabel('_$!!$_', t), 'Ski Cabin');
+ assert.equal(humanizeContactLabel('', t), '');
+ assert.equal(humanizeContactLabel(null, t), '');
+ assert.equal(humanizeContactLabel(undefined, t), '');
+ });
+
+ it('formats vCard values with humanized labels and omits boolean metadata', () => {
+ assert.equal(formatContactValue({
+ kind: 'url',
+ label: '_$!!$_',
+ value: 'https://example.test',
+ }, t), 'Web address: https://example.test');
+ assert.equal(formatContactValue({
+ value: 'ada@example.test',
+ type: 'work',
+ primary: true,
+ }, t), 'ada@example.test · work');
+ });
+
+ it('is presentation only: the stored label still round-trips byte-for-byte', () => {
+ const label = '_$!!$_';
+ const form = contactToForm({
+ additional_fields: [{ id: 'vcard-1', kind: 'url', label, value: 'https://example.test' }],
+ });
+
+ assert.equal(form.additionalFields[0].label, label);
+ assert.equal(formToContactDraft(form).additionalFields[0].label, label);
+ });
+
+ it('humanizes labels in both the detail and the edit rendering', () => {
+ const contactsPage = readFileSync(join(testDir, 'components', 'ContactsPage.jsx'), 'utf8');
+ const detail = contactsPage.slice(
+ contactsPage.indexOf('function ContactDetail'),
+ contactsPage.indexOf('function ContactForm'),
+ );
+ const form = contactsPage.slice(
+ contactsPage.indexOf('function ContactForm'),
+ contactsPage.indexOf('function AdditionalFieldInput'),
+ );
+
+ assert.match(detail, /humanizeContactLabel\(field\.label, t\)/);
+ assert.match(form, /humanizeContactLabel\(field\.label, t\)/);
+ // The edit control still writes the raw value the user typed, never the humanized one.
+ assert.match(form, /onSetAdditional\(field\.id, \{ label: event\.target\.value \}\)/);
+ });
+});
diff --git a/frontend/src/locales/de.json b/frontend/src/locales/de.json
index c8b7f57..54fd0a1 100644
--- a/frontend/src/locales/de.json
+++ b/frontend/src/locales/de.json
@@ -1192,8 +1192,7 @@
},
"carddav": {
"title": "CardDAV-Kontakte",
- "description": "Kontakte von einem CardDAV-Server wie Nextcloud synchronisieren.",
- "connected": "Verbunden",
+ "description": "Kontakte mit einem CardDAV-Server wie Nextcloud synchronisieren.",
"notConnected": "Nicht verbunden",
"serverLabel": "Server-URL",
"serverPh": "https://cloud.beispiel.de",
@@ -1201,10 +1200,6 @@
"userPh": "Ihr Nextcloud-Benutzername",
"passLabel": "App-Passwort",
"passPh": "App-Passwort (nicht Ihr Login-Passwort)",
- "dupLabel": "Wenn ein Kontakt bereits existiert",
- "dupSeparate": "Beide behalten (eigenes Adressbuch)",
- "dupMerge": "Zusammenführen – CardDAV gewinnt",
- "dupSkip": "CardDAV-Kontakt überspringen",
"intervalLabel": "Sync-Intervall (Minuten)",
"connect": "Verbinden",
"connecting": "Verbinde…",
@@ -1215,7 +1210,11 @@
"lastSync": "Letzte Sync: {{when}}",
"summary": "{{contacts}} Kontakte in {{books}} Adressbüchern",
"syncFailed": "Letzte Sync fehlgeschlagen: {{error}}",
- "help": "Verwenden Sie ein Nextcloud-App-Passwort, nicht Ihr Login-Passwort – SSO-Nutzer erstellen es unter Einstellungen → Sicherheit. Kontakte werden einseitig synchronisiert und sind in MailFlow schreibgeschützt."
+ "healthUnavailable": "Status nicht verfügbar",
+ "healthNeedsAttention": "Überprüfung nötig",
+ "healthHealthy": "Fehlerfrei",
+ "reviewConflicts": "Konflikte prüfen",
+ "help": "Verwenden Sie ein Nextcloud-App-Passwort, nicht Ihr Login-Passwort – SSO-Nutzer erstellen es unter Einstellungen → Sicherheit. Kontakte werden in beide Richtungen synchronisiert, wenn der Server Schreibzugriffe erlaubt."
}
},
"ssoLinked": {
@@ -1331,7 +1330,8 @@
"search": "Kontakte suchen…",
"empty": "Noch keine Kontakte",
"noResults": "Keine Kontakte gefunden",
- "count": "{{count}} Kontakte",
+ "count_one": "{{count}} Kontakt",
+ "count_other": "{{count}} Kontakte",
"auto": "auto",
"autoHint": "Aus empfangenen Mails erkannt",
"selectHint": "Kontakt auswählen",
@@ -1360,7 +1360,74 @@
"home": "Privat",
"other": "Sonstige"
},
- "carddavBadge": "Von CardDAV synchronisiert"
+ "carddavSynced": "Mit CardDAV synchronisiert",
+ "carddavReadOnly": "CardDAV nur lesbar",
+ "carddavConflict": "CardDAV-Konflikt",
+ "carddavPending": "Synchronisierung ausstehend",
+ "carddavWriteUnconfirmed": "Ihre Änderung wurde möglicherweise bereits übernommen – der Kontakt wurde aktualisiert. Prüfen Sie ihn und versuchen Sie es bei Bedarf erneut.",
+ "photo": {
+ "title": "Foto",
+ "contactAlt": "Kontaktfoto",
+ "previewAlt": "Vorschau des Kontaktfotos",
+ "present": "Foto vorhanden",
+ "none": "Kein Foto",
+ "choose": "Foto auswählen",
+ "remove": "Foto entfernen",
+ "invalidType": "Wählen Sie ein JPEG- oder PNG-Bild.",
+ "tooLarge": "Das Foto darf höchstens 512 KiB groß sein.",
+ "readFailed": "Das Foto konnte nicht gelesen werden."
+ },
+ "additional": {
+ "title": "Zusätzliche Felder",
+ "label": "Bezeichnung",
+ "value": "Wert",
+ "add": "Feld hinzufügen",
+ "street": "Straße",
+ "extendedAddress": "Adresszusatz",
+ "locality": "Ort",
+ "region": "Bundesland oder Region",
+ "postalCode": "Postleitzahl",
+ "country": "Land",
+ "poBox": "Postfach",
+ "protocol": "Nachrichtendienst",
+ "handle": "Benutzername oder Kennung",
+ "latitude": "Breitengrad",
+ "longitude": "Längengrad",
+ "types": {
+ "postal-address": "Postanschrift",
+ "url": "Webadresse",
+ "im": "Sofortnachricht",
+ "birthday": "Geburtstag",
+ "anniversary": "Jahrestag",
+ "date": "Datum",
+ "role": "Funktion",
+ "title": "Berufsbezeichnung",
+ "nickname": "Spitzname",
+ "geo": "Koordinaten",
+ "custom-text": "Eigener Text"
+ }
+ },
+ "conflicts": {
+ "title": "CardDAV-Konflikte",
+ "count_one": "{{count}} ungelöster Konflikt",
+ "count_other": "{{count}} ungelöste Konflikte",
+ "deleted": "Gelöscht",
+ "photoPresent": "Foto vorhanden",
+ "photoAbsent": "Kein Foto hinterlegt",
+ "loadFailed": "Die Konflikte konnten nicht geladen werden.",
+ "empty": "Keine ungelösten CardDAV-Konflikte.",
+ "item": "Konflikt {{number}}",
+ "mailflowSide": "MailFlow-Version",
+ "carddavSide": "CardDAV-Version",
+ "resolveFailed": "Der Konflikt konnte nicht gelöst werden. Prüfen Sie beide Versionen und versuchen Sie es erneut.",
+ "resolving": "Wird gelöst…",
+ "keepMailflow": "MailFlow-Version behalten",
+ "keepCarddav": "CardDAV-Version behalten",
+ "openCount_one": "{{count}} CardDAV-Konflikt prüfen",
+ "openCount_other": "{{count}} CardDAV-Konflikte prüfen",
+ "refreshFailed": "Der Kontakt konnte nach der Lösung nicht aktualisiert werden.",
+ "close": "Konflikte schließen"
+ }
},
"todoist": {
"betaLabel": "Beta",
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index e594dd2..1e532c3 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -1259,8 +1259,7 @@
},
"carddav": {
"title": "CardDAV Contacts",
- "description": "Sync contacts from a CardDAV server such as Nextcloud.",
- "connected": "Connected",
+ "description": "Sync contacts with a CardDAV server such as Nextcloud.",
"notConnected": "Not connected",
"serverLabel": "Server URL",
"serverPh": "https://cloud.example.com",
@@ -1268,10 +1267,6 @@
"userPh": "your Nextcloud username",
"passLabel": "App password",
"passPh": "app password (not your login password)",
- "dupLabel": "When a contact already exists",
- "dupSeparate": "Keep both (separate address book)",
- "dupMerge": "Merge — CardDAV wins",
- "dupSkip": "Skip the CardDAV contact",
"intervalLabel": "Sync interval (minutes)",
"connect": "Connect",
"connecting": "Connecting…",
@@ -1282,7 +1277,11 @@
"lastSync": "Last sync: {{when}}",
"summary": "{{contacts}} contacts in {{books}} address books",
"syncFailed": "Last sync failed: {{error}}",
- "help": "Use a Nextcloud app password, not your login password — SSO users must create one under Settings → Security. Contacts are synced one-way and are read-only in MailFlow."
+ "healthUnavailable": "Health unavailable",
+ "healthNeedsAttention": "Needs attention",
+ "healthHealthy": "Healthy",
+ "reviewConflicts": "Review conflicts",
+ "help": "Use a Nextcloud app password, not your login password — SSO users must create one under Settings → Security. Contacts sync in both directions when the server allows writes."
}
},
"ssoLinked": {
@@ -1331,7 +1330,8 @@
"search": "Search contacts…",
"empty": "No contacts yet",
"noResults": "No contacts found",
- "count": "{{count}} contacts",
+ "count_one": "{{count}} contact",
+ "count_other": "{{count}} contacts",
"auto": "auto",
"autoHint": "Discovered from received mail",
"selectHint": "Select a contact to view details",
@@ -1360,7 +1360,74 @@
"home": "Home",
"other": "Other"
},
- "carddavBadge": "Synced from CardDAV"
+ "carddavSynced": "Synced with CardDAV",
+ "carddavReadOnly": "Read-only CardDAV",
+ "carddavConflict": "CardDAV conflict",
+ "carddavPending": "Sync pending",
+ "carddavWriteUnconfirmed": "Your change may already have been applied — the contact was refreshed. Check it and try again if needed.",
+ "photo": {
+ "title": "Photo",
+ "contactAlt": "Contact photo",
+ "previewAlt": "Contact photo preview",
+ "present": "Photo available",
+ "none": "No photo",
+ "choose": "Choose photo",
+ "remove": "Remove photo",
+ "invalidType": "Choose a JPEG or PNG image.",
+ "tooLarge": "The photo must be 512 KiB or smaller.",
+ "readFailed": "The photo could not be read."
+ },
+ "additional": {
+ "title": "Additional fields",
+ "label": "Label",
+ "value": "Value",
+ "add": "Add field",
+ "street": "Street",
+ "extendedAddress": "Address details",
+ "locality": "City",
+ "region": "State or region",
+ "postalCode": "Postal code",
+ "country": "Country",
+ "poBox": "PO box",
+ "protocol": "Messaging service",
+ "handle": "Username or handle",
+ "latitude": "Latitude",
+ "longitude": "Longitude",
+ "types": {
+ "postal-address": "Postal address",
+ "url": "Web address",
+ "im": "Instant messaging",
+ "birthday": "Birthday",
+ "anniversary": "Anniversary",
+ "date": "Date",
+ "role": "Role",
+ "title": "Job title",
+ "nickname": "Nickname",
+ "geo": "Coordinates",
+ "custom-text": "Custom text"
+ }
+ },
+ "conflicts": {
+ "title": "CardDAV conflicts",
+ "count_one": "{{count}} unresolved conflict",
+ "count_other": "{{count}} unresolved conflicts",
+ "deleted": "Deleted",
+ "photoPresent": "Photo present",
+ "photoAbsent": "No photo",
+ "loadFailed": "Conflicts could not be loaded.",
+ "empty": "No unresolved CardDAV conflicts.",
+ "item": "Conflict {{number}}",
+ "mailflowSide": "MailFlow version",
+ "carddavSide": "CardDAV version",
+ "resolveFailed": "The conflict could not be resolved. Review both versions and try again.",
+ "resolving": "Resolving…",
+ "keepMailflow": "Keep MailFlow version",
+ "keepCarddav": "Keep CardDAV version",
+ "openCount_one": "Review {{count}} CardDAV conflict",
+ "openCount_other": "Review {{count}} CardDAV conflicts",
+ "refreshFailed": "The contact could not be refreshed after resolution.",
+ "close": "Close conflicts"
+ }
},
"todoist": {
"betaLabel": "Beta",
diff --git a/frontend/src/locales/es.json b/frontend/src/locales/es.json
index f05d569..ec5a466 100644
--- a/frontend/src/locales/es.json
+++ b/frontend/src/locales/es.json
@@ -1259,8 +1259,7 @@
},
"carddav": {
"title": "Contactos CardDAV",
- "description": "Sincroniza contactos desde un servidor CardDAV como Nextcloud.",
- "connected": "Conectado",
+ "description": "Sincroniza contactos con un servidor CardDAV como Nextcloud.",
"notConnected": "No conectado",
"serverLabel": "URL del servidor",
"serverPh": "https://cloud.ejemplo.com",
@@ -1268,10 +1267,6 @@
"userPh": "tu usuario de Nextcloud",
"passLabel": "Contraseña de aplicación",
"passPh": "contraseña de aplicación (no la de inicio de sesión)",
- "dupLabel": "Cuando un contacto ya existe",
- "dupSeparate": "Mantener ambos (libreta separada)",
- "dupMerge": "Combinar: gana CardDAV",
- "dupSkip": "Omitir el contacto CardDAV",
"intervalLabel": "Intervalo de sincronización (minutos)",
"connect": "Conectar",
"connecting": "Conectando…",
@@ -1282,7 +1277,11 @@
"lastSync": "Última sincronización: {{when}}",
"summary": "{{contacts}} contactos en {{books}} libretas",
"syncFailed": "La última sincronización falló: {{error}}",
- "help": "Usa una contraseña de aplicación de Nextcloud, no la de inicio de sesión: los usuarios de SSO deben crear una en Ajustes → Seguridad. Los contactos se sincronizan en un solo sentido y son de solo lectura en MailFlow."
+ "healthUnavailable": "Estado no disponible",
+ "healthNeedsAttention": "Requiere atención",
+ "healthHealthy": "Funcionamiento correcto",
+ "reviewConflicts": "Revisar conflictos",
+ "help": "Usa una contraseña de aplicación de Nextcloud, no la de inicio de sesión: los usuarios de SSO deben crear una en Ajustes → Seguridad. Los contactos se sincronizan en ambos sentidos cuando el servidor permite escribir."
}
},
"ssoLinked": {
@@ -1331,7 +1330,8 @@
"search": "Buscar contactos…",
"empty": "Sin contactos aún",
"noResults": "No se encontraron contactos",
- "count": "{{count}} contactos",
+ "count_one": "{{count}} contacto",
+ "count_other": "{{count}} contactos",
"auto": "auto",
"autoHint": "Descubierto del correo recibido",
"selectHint": "Selecciona un contacto",
@@ -1360,7 +1360,74 @@
"home": "Casa",
"other": "Otro"
},
- "carddavBadge": "Sincronizado desde CardDAV"
+ "carddavSynced": "Sincronizado con CardDAV",
+ "carddavReadOnly": "CardDAV de solo lectura",
+ "carddavConflict": "Conflicto de CardDAV",
+ "carddavPending": "Sincronización pendiente",
+ "carddavWriteUnconfirmed": "Es posible que tu cambio ya se haya aplicado: se actualizó el contacto. Revísalo y vuelve a intentarlo si es necesario.",
+ "photo": {
+ "title": "Fotografía",
+ "contactAlt": "Foto del contacto",
+ "previewAlt": "Vista previa de la foto del contacto",
+ "present": "Foto disponible",
+ "none": "Sin foto",
+ "choose": "Elegir foto",
+ "remove": "Quitar foto",
+ "invalidType": "Elige una imagen JPEG o PNG.",
+ "tooLarge": "La foto debe ocupar 512 KiB o menos.",
+ "readFailed": "No se pudo leer la foto."
+ },
+ "additional": {
+ "title": "Campos adicionales",
+ "label": "Etiqueta",
+ "value": "Valor",
+ "add": "Agregar campo",
+ "street": "Calle",
+ "extendedAddress": "Detalles de dirección",
+ "locality": "Ciudad",
+ "region": "Estado o región",
+ "postalCode": "Código postal",
+ "country": "País",
+ "poBox": "Apartado postal",
+ "protocol": "Servicio de mensajería",
+ "handle": "Usuario o identificador",
+ "latitude": "Latitud",
+ "longitude": "Longitud",
+ "types": {
+ "postal-address": "Dirección postal",
+ "url": "Dirección web",
+ "im": "Mensajería instantánea",
+ "birthday": "Cumpleaños",
+ "anniversary": "Aniversario",
+ "date": "Fecha",
+ "role": "Función",
+ "title": "Cargo profesional",
+ "nickname": "Apodo",
+ "geo": "Coordenadas",
+ "custom-text": "Texto personalizado"
+ }
+ },
+ "conflicts": {
+ "title": "Conflictos de CardDAV",
+ "count_one": "{{count}} conflicto sin resolver",
+ "count_other": "{{count}} conflictos sin resolver",
+ "deleted": "Eliminado",
+ "photoPresent": "Hay una foto",
+ "photoAbsent": "No hay foto",
+ "loadFailed": "No se pudieron cargar los conflictos.",
+ "empty": "No hay conflictos de CardDAV sin resolver.",
+ "item": "Conflicto {{number}}",
+ "mailflowSide": "Versión de MailFlow",
+ "carddavSide": "Versión de CardDAV",
+ "resolveFailed": "No se pudo resolver el conflicto. Revisa ambas versiones e inténtalo de nuevo.",
+ "resolving": "Resolviendo…",
+ "keepMailflow": "Conservar la versión de MailFlow",
+ "keepCarddav": "Conservar la versión de CardDAV",
+ "openCount_one": "Revisar {{count}} conflicto de CardDAV",
+ "openCount_other": "Revisar {{count}} conflictos de CardDAV",
+ "refreshFailed": "No se pudo actualizar el contacto después de resolver el conflicto.",
+ "close": "Cerrar conflictos"
+ }
},
"todoist": {
"betaLabel": "Beta",
diff --git a/frontend/src/locales/fr.json b/frontend/src/locales/fr.json
index 976bc5a..807c7e0 100644
--- a/frontend/src/locales/fr.json
+++ b/frontend/src/locales/fr.json
@@ -1259,8 +1259,7 @@
},
"carddav": {
"title": "Contacts CardDAV",
- "description": "Synchronisez les contacts depuis un serveur CardDAV comme Nextcloud.",
- "connected": "Connecté",
+ "description": "Synchronisez les contacts avec un serveur CardDAV comme Nextcloud.",
"notConnected": "Non connecté",
"serverLabel": "URL du serveur",
"serverPh": "https://cloud.exemple.com",
@@ -1268,10 +1267,6 @@
"userPh": "votre nom d'utilisateur Nextcloud",
"passLabel": "Mot de passe d'application",
"passPh": "mot de passe d'application (pas votre mot de passe de connexion)",
- "dupLabel": "Lorsqu'un contact existe déjà",
- "dupSeparate": "Garder les deux (carnet séparé)",
- "dupMerge": "Fusionner — CardDAV l'emporte",
- "dupSkip": "Ignorer le contact CardDAV",
"intervalLabel": "Intervalle de synchronisation (minutes)",
"connect": "Connecter",
"connecting": "Connexion…",
@@ -1282,7 +1277,11 @@
"lastSync": "Dernière synchro : {{when}}",
"summary": "{{contacts}} contacts dans {{books}} carnets",
"syncFailed": "Échec de la dernière synchro : {{error}}",
- "help": "Utilisez un mot de passe d'application Nextcloud, pas votre mot de passe de connexion — les utilisateurs SSO doivent en créer un dans Paramètres → Sécurité. Les contacts sont synchronisés à sens unique et en lecture seule dans MailFlow."
+ "healthUnavailable": "État indisponible",
+ "healthNeedsAttention": "Intervention nécessaire",
+ "healthHealthy": "Bon fonctionnement",
+ "reviewConflicts": "Examiner les conflits",
+ "help": "Utilisez un mot de passe d’application Nextcloud, pas votre mot de passe de connexion — les utilisateurs SSO doivent en créer un dans Paramètres → Sécurité. Les contacts sont synchronisés dans les deux sens lorsque le serveur autorise l’écriture."
}
},
"ssoLinked": {
@@ -1331,7 +1330,8 @@
"search": "Rechercher des contacts…",
"empty": "Aucun contact pour l'instant",
"noResults": "Aucun contact trouvé",
- "count": "{{count}} contacts",
+ "count_one": "{{count}} contact",
+ "count_other": "{{count}} contacts",
"auto": "auto",
"autoHint": "Découvert depuis les e-mails reçus",
"selectHint": "Sélectionnez un contact",
@@ -1360,7 +1360,74 @@
"home": "Domicile",
"other": "Autre"
},
- "carddavBadge": "Synchronisé depuis CardDAV"
+ "carddavSynced": "Synchronisé avec CardDAV",
+ "carddavReadOnly": "CardDAV en lecture seule",
+ "carddavConflict": "Conflit CardDAV",
+ "carddavPending": "Synchronisation en attente",
+ "carddavWriteUnconfirmed": "Votre modification a peut-être déjà été appliquée : le contact a été actualisé. Vérifiez-le et réessayez si nécessaire.",
+ "photo": {
+ "title": "Photographie",
+ "contactAlt": "Photo du contact",
+ "previewAlt": "Aperçu de la photo du contact",
+ "present": "Photo disponible",
+ "none": "Aucune photo",
+ "choose": "Choisir une photo",
+ "remove": "Retirer la photo",
+ "invalidType": "Choisissez une image JPEG ou PNG.",
+ "tooLarge": "La photo doit faire 512 Kio au maximum.",
+ "readFailed": "La photo n’a pas pu être lue."
+ },
+ "additional": {
+ "title": "Champs supplémentaires",
+ "label": "Libellé",
+ "value": "Valeur",
+ "add": "Ajouter un champ",
+ "street": "Rue",
+ "extendedAddress": "Complément d’adresse",
+ "locality": "Ville",
+ "region": "État ou région",
+ "postalCode": "Code postal",
+ "country": "Pays",
+ "poBox": "Boîte postale",
+ "protocol": "Service de messagerie",
+ "handle": "Nom d’utilisateur ou identifiant",
+ "latitude": "Latitude géographique",
+ "longitude": "Longitude géographique",
+ "types": {
+ "postal-address": "Adresse postale",
+ "url": "Adresse web",
+ "im": "Messagerie instantanée",
+ "birthday": "Date de naissance",
+ "anniversary": "Date anniversaire",
+ "date": "Autre date",
+ "role": "Rôle",
+ "title": "Intitulé du poste",
+ "nickname": "Surnom",
+ "geo": "Coordonnées",
+ "custom-text": "Texte personnalisé"
+ }
+ },
+ "conflicts": {
+ "title": "Conflits CardDAV",
+ "count_one": "{{count}} conflit non résolu",
+ "count_other": "{{count}} conflits non résolus",
+ "deleted": "Supprimé",
+ "photoPresent": "Une photo est présente",
+ "photoAbsent": "Photo absente",
+ "loadFailed": "Impossible de charger les conflits.",
+ "empty": "Aucun conflit CardDAV non résolu.",
+ "item": "Conflit n° {{number}}",
+ "mailflowSide": "Version de MailFlow",
+ "carddavSide": "Version de CardDAV",
+ "resolveFailed": "Impossible de résoudre le conflit. Vérifiez les deux versions et réessayez.",
+ "resolving": "Résolution en cours…",
+ "keepMailflow": "Conserver la version MailFlow",
+ "keepCarddav": "Conserver la version CardDAV",
+ "openCount_one": "Examiner {{count}} conflit CardDAV",
+ "openCount_other": "Examiner {{count}} conflits CardDAV",
+ "refreshFailed": "Impossible d’actualiser le contact après la résolution.",
+ "close": "Fermer les conflits"
+ }
},
"todoist": {
"betaLabel": "Bêta",
diff --git a/frontend/src/locales/i18n.test.js b/frontend/src/locales/i18n.test.js
index e266dc1..d4ffbf1 100644
--- a/frontend/src/locales/i18n.test.js
+++ b/frontend/src/locales/i18n.test.js
@@ -103,6 +103,7 @@ import assert from 'node:assert/strict';
import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
+import i18next from 'i18next';
const dir = dirname(fileURLToPath(import.meta.url));
@@ -258,7 +259,8 @@ const SAME_VALUE_ALLOWED = {
// "auto" — universal technical loanword, same in all locales
'contacts.auto': 'any',
// "contacts" — same word in English and French
- 'contacts.count': [['en', 'fr']],
+ 'contacts.count_one': [['en', 'fr']],
+ 'contacts.count_other': [['en', 'fr']],
'contacts.title': [['en', 'fr']],
// "Email" — international term used as-is in en, es, it, ru, zhCN
'contacts.fields.email': [['en', 'es', 'it', 'ru', 'zhCN']],
@@ -351,6 +353,12 @@ const DYNAMIC_KEYS = new Set([
// appear as literals; the other three do via the tab pills).
'gtd.state.watch',
'gtd.state.delegated',
+ // t(`contacts.additional.types.${kind}`) — remaining Additional-field kinds.
+ 'contacts.additional.types.custom-text',
+ 'contacts.additional.types.date',
+ 'contacts.additional.types.geo',
+ 'contacts.additional.types.im',
+ 'contacts.additional.types.postal-address',
]);
// JSX attribute names whose values must never be plain strings — always t().
@@ -520,14 +528,39 @@ describe('i18n locale files', () => {
describe('key coverage — every key must appear in every locale', () => {
for (const lang of langs) {
it(`${lang} has no missing keys`, () => {
- const present = new Set(Object.keys(locales[lang]));
- const missing = allKeys.filter(k => !present.has(k));
+ const present = new Set(Object.keys(locales[lang]).map(baseKey));
+ const missing = [...new Set(allKeys.map(baseKey))].filter(k => !present.has(k));
assert.equal(missing.length, 0,
`Missing keys:\n${missing.map(k => ` - ${k}`).join('\n')}`);
});
}
});
+ it('uses locale-appropriate CardDAV and contact count plurals', async () => {
+ const bases = ['contacts.count', 'contacts.conflicts.count', 'contacts.conflicts.openCount'];
+ const suffixes = {
+ en: ['one', 'other'], de: ['one', 'other'], es: ['one', 'other'],
+ fr: ['one', 'other'], it: ['one', 'other'], ru: ['one', 'few', 'many'],
+ zhCN: ['other'],
+ };
+ for (const [lang, expected] of Object.entries(suffixes)) {
+ for (const base of bases) {
+ assert.deepEqual(
+ expected.filter(suffix => locales[lang][`${base}_${suffix}`] === undefined),
+ [],
+ `${lang} is missing plural forms for ${base}`,
+ );
+ }
+ }
+
+ const i18n = i18next.createInstance();
+ await i18n.init({
+ lng: 'en',
+ resources: { en: { translation: JSON.parse(readFileSync(join(dir, 'en.json'), 'utf8')) } },
+ });
+ assert.equal(i18n.t('contacts.conflicts.count', { count: 1 }), '1 unresolved conflict');
+ });
+
describe('value uniqueness — no unlisted locale pair should share a value for the same key', () => {
for (const key of allKeys) {
it(key, () => {
@@ -568,3 +601,77 @@ describe('i18n locale files', () => {
});
});
+
+// Regression guard for the contacts type-label overflow — upstream fix b837b93 / PR #242.
+// Stale pre-normalization DB
+// rows can carry a non-canonical contact type (e.g. a raw compound TYPE param like
+// "cell,voice,pref"). A dynamic `t(`contacts.phoneTypes.${type}`)` lookup with no
+// defaultValue returns the raw i18n key, which — being a long, unbreakable token — overflows
+// the fixed-width DetailRow label. DYNAMIC_KEYS above treats these template-literal keys as
+// "referenced", so Suite 1 never validated their runtime resolution and the class slipped past.
+function dynamicTypeLabelOffenders() {
+ const srcDir = resolve(dir, '..'); // frontend/src (excludes node_modules / build output)
+ const offenders = [];
+ (function walk(d) {
+ for (const entry of readdirSync(d, { withFileTypes: true })) {
+ const full = join(d, entry.name);
+ if (entry.isDirectory()) {
+ if (full !== dir) walk(full); // skip locales/ (this test's own directory)
+ continue;
+ }
+ if (!entry.name.endsWith('.jsx') && !entry.name.endsWith('.js')) continue;
+ readFileSync(full, 'utf8').split('\n').forEach((line, i) => {
+ const text = line.trim();
+ if (/contacts\.(?:phone|email)Types\.\$\{/.test(text) && !text.includes('defaultValue')) {
+ offenders.push(`${full.replace(srcDir + '/', '')}:${i + 1} ${text}`);
+ }
+ });
+ }
+ })(srcDir);
+ return offenders;
+}
+
+describe('contacts type labels — humanized fallback, never a raw i18n key', () => {
+ const nested = JSON.parse(readFileSync(join(dir, 'en.json'), 'utf8'));
+
+ it('resolves a non-canonical stored type to the humanized "other" label, not the key', async () => {
+ const i18n = i18next.createInstance();
+ await i18n.init({
+ lng: 'en',
+ fallbackLng: 'en',
+ resources: { en: { translation: nested } },
+ interpolation: { escapeValue: false },
+ });
+
+ const phoneOther = i18n.t('contacts.phoneTypes.other');
+ const emailOther = i18n.t('contacts.emailTypes.other');
+ assert.equal(phoneOther, 'Other'); // the defaultValue target exists and is humanized
+ assert.equal(emailOther, 'Other');
+
+ // A stale compound TYPE value has no canonical key; the guard's defaultValue resolves it
+ // to the humanized fallback instead of "contacts.phoneTypes.cell,voice,pref".
+ for (const type of ['cell,voice,pref', 'internet,work', 'fax']) {
+ const phoneLabel = i18n.t(`contacts.phoneTypes.${type}`, { defaultValue: phoneOther });
+ const emailLabel = i18n.t(`contacts.emailTypes.${type}`, { defaultValue: emailOther });
+ assert.equal(phoneLabel, 'Other');
+ assert.equal(emailLabel, 'Other');
+ assert.doesNotMatch(phoneLabel, /contacts\.(?:phone|email)Types\./);
+ assert.doesNotMatch(emailLabel, /contacts\.(?:phone|email)Types\./);
+ }
+
+ // The cell/iphone→mobile alias lands on the real canonical label.
+ assert.equal(i18n.t('contacts.phoneTypes.mobile', { defaultValue: phoneOther }), 'Mobile');
+
+ // Characterization of the underlying bug: WITHOUT the defaultValue, i18next returns the key.
+ assert.equal(i18n.t('contacts.phoneTypes.cell,voice,pref'),
+ 'contacts.phoneTypes.cell,voice,pref');
+ });
+
+ it('never lets a dynamic contacts type-label lookup omit its defaultValue guard', () => {
+ const offenders = dynamicTypeLabelOffenders();
+ assert.deepEqual(offenders, [],
+ 'A dynamic contacts type-label lookup with no { defaultValue } renders the raw i18n key '
+ + 'for a non-canonical stored type (see b837b93 / PR #242):\n'
+ + offenders.map(line => ` ${line}`).join('\n'));
+ });
+});
diff --git a/frontend/src/locales/it.json b/frontend/src/locales/it.json
index 1368084..10daf2e 100644
--- a/frontend/src/locales/it.json
+++ b/frontend/src/locales/it.json
@@ -1259,8 +1259,7 @@
},
"carddav": {
"title": "Contatti CardDAV",
- "description": "Sincronizza i contatti da un server CardDAV come Nextcloud.",
- "connected": "Connesso",
+ "description": "Sincronizza i contatti con un server CardDAV come Nextcloud.",
"notConnected": "Non connesso",
"serverLabel": "URL del server",
"serverPh": "https://cloud.esempio.com",
@@ -1268,10 +1267,6 @@
"userPh": "il tuo nome utente Nextcloud",
"passLabel": "Password dell'app",
"passPh": "password app (non quella di accesso)",
- "dupLabel": "Quando un contatto esiste già",
- "dupSeparate": "Mantieni entrambi (rubrica separata)",
- "dupMerge": "Unisci — vince CardDAV",
- "dupSkip": "Salta il contatto CardDAV",
"intervalLabel": "Intervallo di sincronizzazione (minuti)",
"connect": "Connetti",
"connecting": "Connessione…",
@@ -1282,7 +1277,11 @@
"lastSync": "Ultima sincronizzazione: {{when}}",
"summary": "{{contacts}} contatti in {{books}} rubriche",
"syncFailed": "Ultima sincronizzazione non riuscita: {{error}}",
- "help": "Usa una password app di Nextcloud, non quella di accesso: gli utenti SSO devono crearne una in Impostazioni → Sicurezza. I contatti sono sincronizzati a senso unico e di sola lettura in MailFlow."
+ "healthUnavailable": "Stato non disponibile",
+ "healthNeedsAttention": "Richiede attenzione",
+ "healthHealthy": "Servizio regolare",
+ "reviewConflicts": "Esamina i conflitti",
+ "help": "Usa una password app di Nextcloud, non quella di accesso: gli utenti SSO devono crearne una in Impostazioni → Sicurezza. I contatti vengono sincronizzati in entrambe le direzioni quando il server consente la scrittura."
}
},
"ssoLinked": {
@@ -1331,7 +1330,8 @@
"search": "Cerca contatti…",
"empty": "Nessun contatto ancora",
"noResults": "Nessun contatto trovato",
- "count": "{{count}} contatti",
+ "count_one": "{{count}} contatto",
+ "count_other": "{{count}} contatti",
"auto": "auto",
"autoHint": "Rilevato da email ricevute",
"selectHint": "Seleziona un contatto",
@@ -1360,7 +1360,74 @@
"home": "Casa",
"other": "Altro"
},
- "carddavBadge": "Sincronizzato da CardDAV"
+ "carddavSynced": "Sincronizzato con CardDAV",
+ "carddavReadOnly": "CardDAV in sola lettura",
+ "carddavConflict": "Conflitto CardDAV",
+ "carddavPending": "Sincronizzazione in sospeso",
+ "carddavWriteUnconfirmed": "La tua modifica potrebbe essere già stata applicata: il contatto è stato aggiornato. Verifica e riprova se necessario.",
+ "photo": {
+ "title": "Immagine",
+ "contactAlt": "Foto del contatto",
+ "previewAlt": "Anteprima della foto del contatto",
+ "present": "Foto disponibile",
+ "none": "Nessuna foto",
+ "choose": "Scegli foto",
+ "remove": "Rimuovi foto",
+ "invalidType": "Scegli un’immagine JPEG o PNG.",
+ "tooLarge": "La foto deve essere di 512 KiB o meno.",
+ "readFailed": "Non è stato possibile leggere la foto."
+ },
+ "additional": {
+ "title": "Campi aggiuntivi",
+ "label": "Etichetta",
+ "value": "Contenuto",
+ "add": "Aggiungi campo",
+ "street": "Via",
+ "extendedAddress": "Dettagli indirizzo",
+ "locality": "Città",
+ "region": "Provincia o regione",
+ "postalCode": "Codice postale",
+ "country": "Paese",
+ "poBox": "Casella postale",
+ "protocol": "Servizio di messaggistica",
+ "handle": "Utente o identificativo",
+ "latitude": "Latitudine nord-sud",
+ "longitude": "Longitudine est-ovest",
+ "types": {
+ "postal-address": "Indirizzo postale",
+ "url": "Indirizzo web",
+ "im": "Messaggistica istantanea",
+ "birthday": "Compleanno",
+ "anniversary": "Ricorrenza",
+ "date": "Data personale",
+ "role": "Ruolo",
+ "title": "Titolo professionale",
+ "nickname": "Soprannome",
+ "geo": "Coordinate",
+ "custom-text": "Testo personalizzato"
+ }
+ },
+ "conflicts": {
+ "title": "Conflitti CardDAV",
+ "count_one": "{{count}} conflitto non risolto",
+ "count_other": "{{count}} conflitti non risolti",
+ "deleted": "Cancellato",
+ "photoPresent": "Foto presente",
+ "photoAbsent": "Foto non presente",
+ "loadFailed": "Impossibile caricare i conflitti.",
+ "empty": "Non ci sono conflitti CardDAV irrisolti.",
+ "item": "Conflitto numero {{number}}",
+ "mailflowSide": "Versione MailFlow",
+ "carddavSide": "Versione CardDAV",
+ "resolveFailed": "Impossibile risolvere il conflitto. Controlla entrambe le versioni e riprova.",
+ "resolving": "Risoluzione…",
+ "keepMailflow": "Mantieni la versione MailFlow",
+ "keepCarddav": "Mantieni la versione CardDAV",
+ "openCount_one": "Esamina {{count}} conflitto CardDAV",
+ "openCount_other": "Esamina {{count}} conflitti CardDAV",
+ "refreshFailed": "Impossibile aggiornare il contatto dopo la risoluzione.",
+ "close": "Chiudi i conflitti"
+ }
},
"todoist": {
"betaLabel": "Beta",
diff --git a/frontend/src/locales/ru.json b/frontend/src/locales/ru.json
index 3fba0b0..8b49e37 100644
--- a/frontend/src/locales/ru.json
+++ b/frontend/src/locales/ru.json
@@ -1259,8 +1259,7 @@
},
"carddav": {
"title": "Контакты CardDAV",
- "description": "Синхронизация контактов с сервера CardDAV, например Nextcloud.",
- "connected": "Подключено",
+ "description": "Синхронизация контактов с сервером CardDAV, например Nextcloud.",
"notConnected": "Не подключено",
"serverLabel": "URL сервера",
"serverPh": "https://cloud.example.ru",
@@ -1268,10 +1267,6 @@
"userPh": "ваше имя пользователя Nextcloud",
"passLabel": "Пароль приложения",
"passPh": "пароль приложения (не пароль для входа)",
- "dupLabel": "Когда контакт уже существует",
- "dupSeparate": "Оставить оба (отдельная книга)",
- "dupMerge": "Объединить — приоритет CardDAV",
- "dupSkip": "Пропустить контакт CardDAV",
"intervalLabel": "Интервал синхронизации (минуты)",
"connect": "Подключить",
"connecting": "Подключение…",
@@ -1282,7 +1277,11 @@
"lastSync": "Последняя синхронизация: {{when}}",
"summary": "{{contacts}} контактов в {{books}} книгах",
"syncFailed": "Последняя синхронизация не удалась: {{error}}",
- "help": "Используйте пароль приложения Nextcloud, а не пароль для входа — пользователям SSO нужно создать его в Настройки → Безопасность. Контакты синхронизируются в одну сторону и доступны только для чтения в MailFlow."
+ "healthUnavailable": "Состояние недоступно",
+ "healthNeedsAttention": "Требует внимания",
+ "healthHealthy": "Работает исправно",
+ "reviewConflicts": "Проверить конфликты",
+ "help": "Используйте пароль приложения Nextcloud, а не пароль для входа — пользователям SSO нужно создать его в Настройки → Безопасность. Контакты синхронизируются в обоих направлениях, если сервер разрешает запись."
}
},
"ssoLinked": {
@@ -1331,7 +1330,9 @@
"search": "Поиск контактов…",
"empty": "Нет контактов",
"noResults": "Контакты не найдены",
- "count": "{{count}} контактов",
+ "count_one": "{{count}} контакт",
+ "count_few": "{{count}} контакта",
+ "count_many": "{{count}} контактов",
"auto": "auto",
"autoHint": "Обнаружен из входящей почты",
"selectHint": "Выберите контакт",
@@ -1360,7 +1361,76 @@
"home": "Дом",
"other": "Другой"
},
- "carddavBadge": "Синхронизировано из CardDAV"
+ "carddavSynced": "Синхронизировано с CardDAV",
+ "carddavReadOnly": "CardDAV только для чтения",
+ "carddavConflict": "Конфликт CardDAV",
+ "carddavPending": "Ожидает синхронизации",
+ "carddavWriteUnconfirmed": "Возможно, изменение уже применено — контакт обновлён. Проверьте его и при необходимости повторите.",
+ "photo": {
+ "title": "Фотография",
+ "contactAlt": "Фотография контакта",
+ "previewAlt": "Предпросмотр фотографии контакта",
+ "present": "Фотография доступна",
+ "none": "Фотографии нет",
+ "choose": "Выбрать фотографию",
+ "remove": "Удалить фотографию",
+ "invalidType": "Выберите изображение JPEG или PNG.",
+ "tooLarge": "Размер фотографии не должен превышать 512 КиБ.",
+ "readFailed": "Не удалось прочитать фотографию."
+ },
+ "additional": {
+ "title": "Дополнительные поля",
+ "label": "Подпись",
+ "value": "Значение",
+ "add": "Добавить поле",
+ "street": "Улица",
+ "extendedAddress": "Дополнение к адресу",
+ "locality": "Город",
+ "region": "Область или регион",
+ "postalCode": "Почтовый индекс",
+ "country": "Страна",
+ "poBox": "Абонентский ящик",
+ "protocol": "Служба сообщений",
+ "handle": "Имя пользователя или идентификатор",
+ "latitude": "Географическая широта",
+ "longitude": "Географическая долгота",
+ "types": {
+ "postal-address": "Почтовый адрес",
+ "url": "Веб-адрес",
+ "im": "Мгновенные сообщения",
+ "birthday": "День рождения",
+ "anniversary": "Годовщина",
+ "date": "Особая дата",
+ "role": "Роль",
+ "title": "Должность",
+ "nickname": "Псевдоним",
+ "geo": "Координаты",
+ "custom-text": "Произвольный текст"
+ }
+ },
+ "conflicts": {
+ "title": "Конфликты CardDAV",
+ "count_one": "{{count}} неразрешённый конфликт",
+ "count_few": "{{count}} неразрешённых конфликта",
+ "count_many": "{{count}} неразрешённых конфликтов",
+ "deleted": "Удалено",
+ "photoPresent": "Фотография присутствует",
+ "photoAbsent": "Фотография отсутствует",
+ "loadFailed": "Не удалось загрузить конфликты.",
+ "empty": "Неразрешённых конфликтов CardDAV нет.",
+ "item": "Конфликт № {{number}}",
+ "mailflowSide": "Версия MailFlow",
+ "carddavSide": "Версия CardDAV",
+ "resolveFailed": "Не удалось разрешить конфликт. Проверьте обе версии и повторите попытку.",
+ "resolving": "Разрешение…",
+ "keepMailflow": "Оставить версию MailFlow",
+ "keepCarddav": "Оставить версию CardDAV",
+ "openCount_one": "Проверить {{count}} конфликт CardDAV",
+ "openCount_few": "Проверить {{count}} конфликта CardDAV",
+ "openCount_many": "Проверить {{count}} конфликтов CardDAV",
+ "refreshFailed": "Не удалось обновить контакт после разрешения конфликта.",
+ "close": "Закрыть конфликты"
+ }
},
"todoist": {
"betaLabel": "Бета",
diff --git a/frontend/src/locales/zhCN.json b/frontend/src/locales/zhCN.json
index 09edcc9..3dec5a5 100644
--- a/frontend/src/locales/zhCN.json
+++ b/frontend/src/locales/zhCN.json
@@ -1259,8 +1259,7 @@
},
"carddav": {
"title": "CardDAV 联系人",
- "description": "从 Nextcloud 等 CardDAV 服务器同步联系人。",
- "connected": "已连接",
+ "description": "与 Nextcloud 等 CardDAV 服务器同步联系人。",
"notConnected": "未连接",
"serverLabel": "服务器地址",
"serverPh": "https://nextcloud.example.com",
@@ -1268,10 +1267,6 @@
"userPh": "你的 Nextcloud 用户名",
"passLabel": "应用专用密码",
"passPh": "应用专用密码（非登录密码）",
- "dupLabel": "当联系人已存在时",
- "dupSeparate": "保留两者（单独的通讯簿）",
- "dupMerge": "合并 — 以 CardDAV 为准",
- "dupSkip": "跳过该 CardDAV 联系人",
"intervalLabel": "同步间隔（分钟）",
"connect": "连接",
"connecting": "正在连接…",
@@ -1282,7 +1277,11 @@
"lastSync": "上次同步：{{when}}",
"summary": "{{books}} 个通讯簿中的 {{contacts}} 个联系人",
"syncFailed": "上次同步失败：{{error}}",
- "help": "请使用 Nextcloud 应用专用密码，而非登录密码——SSO 用户需在“设置 → 安全”中创建。联系人为单向同步，在 MailFlow 中为只读。"
+ "healthUnavailable": "无法获取运行状态",
+ "healthNeedsAttention": "需要处理",
+ "healthHealthy": "运行正常",
+ "reviewConflicts": "查看冲突",
+ "help": "请使用 Nextcloud 应用专用密码，而非登录密码——SSO 用户需在“设置 → 安全”中创建。当服务器允许写入时，联系人会双向同步。"
}
},
"ssoLinked": {
@@ -1331,7 +1330,7 @@
"search": "搜索联系人…",
"empty": "暂无联系人",
"noResults": "未找到联系人",
- "count": "{{count}} 个联系人",
+ "count_other": "{{count}} 个联系人",
"auto": "auto",
"autoHint": "从收件中自动发现",
"selectHint": "选择联系人",
@@ -1360,7 +1359,72 @@
"home": "家庭",
"other": "其他"
},
- "carddavBadge": "从 CardDAV 同步"
+ "carddavSynced": "已与 CardDAV 同步",
+ "carddavReadOnly": "CardDAV 只读联系人",
+ "carddavConflict": "CardDAV 数据冲突",
+ "carddavPending": "同步待处理",
+ "carddavWriteUnconfirmed": "您的更改可能已经生效——联系人已刷新。请检查后按需重试。",
+ "photo": {
+ "title": "头像",
+ "contactAlt": "联系人头像",
+ "previewAlt": "联系人头像预览",
+ "present": "已有头像",
+ "none": "暂无头像",
+ "choose": "选择头像",
+ "remove": "移除头像",
+ "invalidType": "请选择 JPEG 或 PNG 图片。",
+ "tooLarge": "头像大小不得超过 512 KiB。",
+ "readFailed": "无法读取所选头像。"
+ },
+ "additional": {
+ "title": "其他信息",
+ "label": "字段名称",
+ "value": "字段内容",
+ "add": "添加字段",
+ "street": "街道",
+ "extendedAddress": "详细地址",
+ "locality": "城市",
+ "region": "省份或地区",
+ "postalCode": "邮政编码",
+ "country": "国家或地区",
+ "poBox": "邮政信箱",
+ "protocol": "通讯服务",
+ "handle": "用户名或账号",
+ "latitude": "纬度",
+ "longitude": "经度",
+ "types": {
+ "postal-address": "邮寄地址",
+ "url": "网址",
+ "im": "即时通讯",
+ "birthday": "生日",
+ "anniversary": "纪念日",
+ "date": "其他日期",
+ "role": "职务",
+ "title": "职位名称",
+ "nickname": "昵称",
+ "geo": "地理坐标",
+ "custom-text": "自定义文本"
+ }
+ },
+ "conflicts": {
+ "title": "CardDAV 冲突",
+ "count_other": "{{count}} 个未解决的冲突",
+ "deleted": "已删除",
+ "photoPresent": "包含头像",
+ "photoAbsent": "不含头像",
+ "loadFailed": "无法加载冲突列表。",
+ "empty": "没有未解决的 CardDAV 冲突。",
+ "item": "第 {{number}} 个冲突",
+ "mailflowSide": "MailFlow 中的版本",
+ "carddavSide": "CardDAV 中的版本",
+ "resolveFailed": "无法解决此冲突。请检查两个版本后重试。",
+ "resolving": "正在解决…",
+ "keepMailflow": "保留 MailFlow 版本",
+ "keepCarddav": "保留 CardDAV 版本",
+ "openCount_other": "查看 {{count}} 个 CardDAV 冲突",
+ "refreshFailed": "解决冲突后无法刷新联系人。",
+ "close": "关闭冲突列表"
+ }
},
"todoist": {
"betaLabel": "测试版",
diff --git a/frontend/src/utils/api.js b/frontend/src/utils/api.js
index 64e1346..3697d35 100644
--- a/frontend/src/utils/api.js
+++ b/frontend/src/utils/api.js
@@ -23,8 +23,12 @@ async function request(method, path, body, extraHeaders) {
if (res.status === 401 && !path.startsWith('/auth/')) {
window.dispatchEvent(new CustomEvent('mailflow:session_expired'));
}
- const err = await res.json().catch(() => ({ error: 'Request failed' }));
- throw new Error(err.error || 'Request failed');
+ const data = await res.json().catch(() => ({ error: 'Request failed' }));
+ const error = new Error(data.error || 'Request failed');
+ error.status = res.status;
+ error.data = data;
+ if (typeof data.conflictId === 'string') error.conflictId = data.conflictId;
+ throw error;
}
return res.json();
}
@@ -211,6 +215,12 @@ export const api = {
update: (data) => request('PATCH', '/carddav', data),
sync: () => request('POST', '/carddav/sync'),
disconnect: () => request('DELETE', '/carddav'),
+ getConflicts: () => request('GET', '/carddav/conflicts'),
+ resolveConflict: (id, resolution) => request(
+ 'POST',
+ `/carddav/conflicts/${encodeURIComponent(id)}/resolve`,
+ { resolution },
+ ),
},
// Image whitelist
From ee2453ea0cc9b3259bff594e128c5abbd0339a29 Mon Sep 17 00:00:00 2001
From: salmonumbrella <182032677+salmonumbrella@users.noreply.github.com>
Date: Mon, 13 Jul 2026 22:18:57 -0700
Subject: [PATCH 2/2] feat: per-book roles for CardDAV multi-address-book sync
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
A CardDAV credential often exposes several address books — a curated
"Apple Contacts" book next to the "Email contacts" book MailFlow should
write to. Pulling every book and writing into whichever came first
flooded the contact list and risked writing into a curated book. Each
book now carries explicit roles, managed per book in the admin panel
and enforced across sync, export, and conflict handling:
- Write target: exactly one per account; every MailFlow-originated
create/update/delete goes there and nowhere else. A stable alias
keeps the role when re-discovery changes the book's canonical URL.
- Subscribed: pulled and shown in the contact list.
- Lookup source: pulled into the sync ledger only, to resolve inbound
senders (names, avatars) without materializing contacts.
- Neither: ignored entirely; its ledger rows are dropped.
Publication into a shared book becomes a deliberate act. Editing an
auto-collected contact no longer silently publishes it; an explicit
promote action does. Sending mail to someone still marks them explicit
for autocomplete but no longer publishes them: a new
publishEmailedContacts setting (default OFF) gates that, and turning it
ON restores a book that fills with everyone you correspond with.
Default OFF means nothing new reaches a shared address book without a
deliberate act. The gate is a separate carddav_publish_intent column,
so send.js is untouched and autocomplete ranking on is_auto is
unaffected; contacts already exporting keep exporting via the backfill.
The role model follows JMAP's isDefault/isSubscribed split rather than
a single flag.
Migrations 0038-0040 add role, alias, and publish-intent columns with
behaviour-preserving backfills; the only pre-existing object touched is
a widened mapping-status CHECK constraint.
---
.../migrations/0038_carddav_multi_book.sql | 63 +
.../0039_carddav_write_target_alias.sql | 12 +
.../0040_carddav_publish_intent.sql | 20 +
backend/src/routes/carddav.test.js | 17 +
backend/src/routes/carddavAccount.js | 87 +-
backend/src/routes/carddavAccount.test.js | 144 ++
backend/src/routes/carddavConflicts.js | 1 +
backend/src/routes/contacts.js | 34 +-
backend/src/routes/contacts.test.js | 115 +-
.../src/services/carddavConflictService.js | 48 +-
.../services/carddavConflictService.test.js | 39 +
.../carddavContactService.integration.test.js | 334 ++-
backend/src/services/carddavContactService.js | 187 +-
.../services/carddavContactService.test.js | 241 ++-
backend/src/services/carddavLookupService.js | 156 ++
.../src/services/carddavLookupService.test.js | 149 ++
backend/src/services/carddavMappingState.js | 345 ++-
.../src/services/carddavMappingState.test.js | 439 +++-
.../src/services/carddavMigration.db.test.js | 257 ++-
backend/src/services/carddavSync.db.test.js | 686 +++++-
.../services/carddavSync.integration.test.js | 1877 +++++++++++++++--
backend/src/services/carddavSync.js | 945 ++++++++-
backend/src/services/carddavSync.test.js | 420 +++-
backend/src/services/messageService.js | 92 +-
backend/src/services/messageService.test.js | 104 +
frontend/src/carddavBookState.js | 56 +
frontend/src/carddavBookState.test.js | 104 +
frontend/src/components/AdminPanel.jsx | 128 ++
frontend/src/components/ContactsPage.jsx | 66 +-
frontend/src/contactCarddavState.js | 38 +
frontend/src/contactCarddavState.test.js | 78 +
frontend/src/locales/de.json | 27 +-
frontend/src/locales/en.json | 27 +-
frontend/src/locales/es.json | 27 +-
frontend/src/locales/fr.json | 27 +-
frontend/src/locales/i18n.test.js | 9 +
frontend/src/locales/it.json | 27 +-
frontend/src/locales/ru.json | 27 +-
frontend/src/locales/zhCN.json | 27 +-
frontend/src/utils/api.js | 4 +
40 files changed, 7168 insertions(+), 316 deletions(-)
create mode 100644 backend/migrations/0038_carddav_multi_book.sql
create mode 100644 backend/migrations/0039_carddav_write_target_alias.sql
create mode 100644 backend/migrations/0040_carddav_publish_intent.sql
create mode 100644 backend/src/services/carddavLookupService.js
create mode 100644 backend/src/services/carddavLookupService.test.js
create mode 100644 frontend/src/carddavBookState.js
create mode 100644 frontend/src/carddavBookState.test.js
diff --git a/backend/migrations/0038_carddav_multi_book.sql b/backend/migrations/0038_carddav_multi_book.sql
new file mode 100644
index 0000000..bfb1208
--- /dev/null
+++ b/backend/migrations/0038_carddav_multi_book.sql
@@ -0,0 +1,63 @@
+-- Multi-address-book CardDAV: surface per-book roles (write-target /
+-- subscribed / lookup-only) so a connected server exposing several address
+-- books can be treated by role rather than symmetrically. This migration is
+-- schema-only — it does not change sync
+-- behavior. Backfill preserves today's behavior exactly: every existing
+-- carddav book stays subscribed + lookup, and the first create-capable book
+-- per user becomes the write-target (mirroring the current selectedCreateBook
+-- rule), so no existing user's write destination changes.
+
+ALTER TABLE address_books
+ ADD COLUMN IF NOT EXISTS is_write_target BOOLEAN NOT NULL DEFAULT false,
+ ADD COLUMN IF NOT EXISTS is_subscribed BOOLEAN NOT NULL DEFAULT false,
+ ADD COLUMN IF NOT EXISTS is_lookup_source BOOLEAN NOT NULL DEFAULT true;
+
+DO $$
+BEGIN
+ IF NOT EXISTS (
+ SELECT 1 FROM pg_constraint
+ WHERE conname = 'address_books_write_target_subscribed'
+ AND conrelid = 'address_books'::regclass
+ ) THEN
+ ALTER TABLE address_books
+ ADD CONSTRAINT address_books_write_target_subscribed
+ CHECK (NOT is_write_target OR is_subscribed);
+ END IF;
+END $$;
+
+-- At most one write-target per user among carddav books.
+CREATE UNIQUE INDEX IF NOT EXISTS carddav_one_write_target_idx
+ ON address_books (user_id)
+ WHERE source = 'carddav' AND is_write_target;
+
+-- Backfill: preserve today's behavior for existing single/multi-book users.
+UPDATE address_books
+ SET is_subscribed = true, is_lookup_source = true
+ WHERE source = 'carddav';
+
+-- First create-capable book per user becomes the write-target (mirrors the
+-- current selectedCreateBook rule; tie-break by insertion order).
+WITH ranked AS (
+ SELECT id, row_number() OVER (
+ PARTITION BY user_id
+ ORDER BY (remote_create_capability = 'allowed') DESC, created_at, id
+ ) AS position
+ FROM address_books
+ WHERE source = 'carddav'
+ AND remote_create_capability IN ('allowed', 'unknown')
+)
+UPDATE address_books SET is_write_target = true
+ WHERE id IN (SELECT id FROM ranked WHERE position = 1);
+
+-- Ledger gains a terminal 'lookup' status and a projected display name.
+ALTER TABLE carddav_remote_objects
+ DROP CONSTRAINT IF EXISTS carddav_remote_objects_mapping_status_check,
+ ADD CONSTRAINT carddav_remote_objects_mapping_status_check
+ CHECK (mapping_status IN
+ ('pending_materialization','synced','pending_push','conflict','lookup')),
+ ADD COLUMN IF NOT EXISTS lookup_display_name TEXT;
+
+-- Fast inbound lookup by email across a user's lookup books.
+CREATE INDEX IF NOT EXISTS carddav_lookup_email_idx
+ ON carddav_remote_objects (primary_email)
+ WHERE mapping_status = 'lookup';
diff --git a/backend/migrations/0039_carddav_write_target_alias.sql b/backend/migrations/0039_carddav_write_target_alias.sql
new file mode 100644
index 0000000..13d56a0
--- /dev/null
+++ b/backend/migrations/0039_carddav_write_target_alias.sql
@@ -0,0 +1,12 @@
+-- Multi-address-book CardDAV follow-up: write-target routing
+-- resolves the stored is_write_target book against a fresh CardDAV discovery
+-- snapshot by URL. Some servers advertise a stable "alias" href in PROPFIND
+-- discovery that 3xx-redirects (REPORT/PUT/DELETE) to a different canonical
+-- collection URL; carddavSync.js already detects and reconciles this by
+-- rewriting address_books.external_url to the canonical URL, but discovery
+-- keeps returning the alias forever afterward. Record the alias alongside the
+-- canonical URL so write-target resolution (and the export sweep) can match
+-- either, instead of a fresh discovery snapshot falsely reporting the
+-- write-target missing. Additive only — no existing column or row changes.
+ALTER TABLE address_books
+ ADD COLUMN IF NOT EXISTS discovery_alias_url TEXT;
diff --git a/backend/migrations/0040_carddav_publish_intent.sql b/backend/migrations/0040_carddav_publish_intent.sql
new file mode 100644
index 0000000..b12beff
--- /dev/null
+++ b/backend/migrations/0040_carddav_publish_intent.sql
@@ -0,0 +1,20 @@
+-- Multi-address-book CardDAV: separate "the user deliberately wants
+-- this contact in their address book" from is_auto.
+--
+-- routes/send.js sets is_auto = false on any contact the user sends mail to, and
+-- routes/search.js ranks autocomplete on exactly that flag ("contacts the user
+-- explicitly sent to or manually created"). is_auto therefore cannot also mean
+-- "publish this to CardDAV" — gating publication on it means replying to a
+-- harvested sender silently pushes them into the user's shared address book.
+-- Publication is gated on this column instead; is_auto keeps its upstream meaning
+-- and send.js is untouched, so autocomplete ranking is unaffected.
+--
+-- Backfill = NOT is_auto: every contact that is explicit on the old schema is
+-- being exported by the sweep today, so it keeps exporting. The false default
+-- applies only to rows created from here on, where a contact that became explicit
+-- merely by being emailed is not published until the user deliberately promotes
+-- it (or turns on the publishEmailedContacts setting).
+ALTER TABLE contacts
+ ADD COLUMN IF NOT EXISTS carddav_publish_intent BOOLEAN NOT NULL DEFAULT false;
+
+UPDATE contacts SET carddav_publish_intent = true WHERE is_auto = false;
diff --git a/backend/src/routes/carddav.test.js b/backend/src/routes/carddav.test.js
index 3484bdf..6af63a2 100644
--- a/backend/src/routes/carddav.test.js
+++ b/backend/src/routes/carddav.test.js
@@ -34,6 +34,9 @@ vi.mock('../services/carddavContactService.js', () => ({
ERR_CARDDAV_AMBIGUOUS_WRITE: 409,
ERR_CARDDAV_PENDING_INTENT: 409,
ERR_CARDDAV_READ_ONLY: 403,
+ ERR_CARDDAV_NO_WRITE_TARGET: 409,
+ ERR_CARDDAV_NOT_CONNECTED: 409,
+ ERR_CARDDAV_ALREADY_MAPPED: 409,
'23505': 409,
},
createContactFromVCard: mocks.createContactFromVCard,
@@ -429,6 +432,20 @@ describe('PUT CardDAV contact resource', () => {
expect(res.end).toHaveBeenCalled();
});
+ it('maps a missing write-target failure to 409 with no fallback', async () => {
+ mockResource(null);
+ mocks.createContactFromVCard.mockRejectedValueOnce(Object.assign(
+ new Error('No CardDAV write-target address book is configured'),
+ { code: 'ERR_CARDDAV_NO_WRITE_TARGET' },
+ ));
+ const res = response();
+
+ await putHandler(request({ headers: { 'if-none-match': '*' } }), res);
+
+ expect(res.status).toHaveBeenCalledWith(409);
+ expect(res.end).toHaveBeenCalled();
+ });
+
it('returns 412 without delegation when If-Match does not match confirmed local state', async () => {
mockResource();
const res = response();
diff --git a/backend/src/routes/carddavAccount.js b/backend/src/routes/carddavAccount.js
index d3c0eb8..2d182a3 100644
--- a/backend/src/routes/carddavAccount.js
+++ b/backend/src/routes/carddavAccount.js
@@ -14,9 +14,12 @@ import {
requestCarddavSync,
scheduleCardavUser,
getCardavConfig,
+ getCarddavBookSummaries,
+ patchCarddavBookRoles,
replaceCarddavConnection,
patchCarddavConnection,
disconnectCarddavAccount,
+ StaleCarddavPlanError,
} from '../services/carddavSync.js';
const router = Router();
@@ -24,8 +27,10 @@ router.use(requireAuth);
const clampInterval = (v) => Math.max(15, Math.min(1440, parseInt(v) || 60));
-// Public view of the connection — never leaks the stored password.
-function publicStatus(config) {
+// Public view of the connection — never leaks the stored password. `books` is
+// a per-book read-only summary (roles, capabilities, counts); `bookCount`/
+// `contactCount` remain as aggregate counts for backward compatibility.
+async function publicStatus(config, userId) {
if (!config?.serverUrl) return { connected: false };
return {
connected: true,
@@ -36,11 +41,15 @@ function publicStatus(config) {
lastError: config.lastError || null,
bookCount: config.bookCount ?? null,
contactCount: config.contactCount ?? null,
+ // Absent on every connection made before this setting existed, which must
+ // read as OFF — see the export sweep in carddavSync.js.
+ publishEmailedContacts: config.publishEmailedContacts === true,
+ books: await getCarddavBookSummaries(userId),
};
}
router.get('/', async (req, res) => {
- res.json(publicStatus(await getCardavConfig(req.session.userId)));
+ res.json(await publicStatus(await getCardavConfig(req.session.userId), req.session.userId));
});
router.post('/connect', async (req, res) => {
@@ -89,16 +98,26 @@ router.post('/connect', async (req, res) => {
scheduleCardavUser(req.session.userId, config.intervalMin);
// Kick off the first sync in the background; the client polls GET / for status.
requestCarddavSync(req.session.userId, config.connectionGeneration);
- res.json(publicStatus(config));
+ res.json(await publicStatus(config, req.session.userId));
});
-// Update the interval (and optionally rotate the password).
+// Update the interval and the publish-emailed-contacts setting (and optionally
+// rotate the password).
router.patch('/', async (req, res) => {
const existing = await getCardavConfig(req.session.userId);
if (!existing?.serverUrl) return res.status(409).json({ error: 'CardDAV not connected' });
const patch = {};
if (req.body.intervalMin != null) patch.intervalMin = clampInterval(req.body.intervalMin);
+ // Stored strictly as a boolean: this setting decides whether merely emailing
+ // someone publishes them to a shared address book, so a stray truthy value must
+ // never turn it on.
+ if (req.body.publishEmailedContacts != null) {
+ if (typeof req.body.publishEmailedContacts !== 'boolean') {
+ return res.status(400).json({ error: 'publishEmailedContacts must be a boolean' });
+ }
+ patch.publishEmailedContacts = req.body.publishEmailedContacts;
+ }
if (req.body.password) {
const policy = await getConnectionPolicy();
try {
@@ -119,14 +138,68 @@ router.patch('/', async (req, res) => {
: await patchCarddavConnection(req.session.userId, patch);
if (patch.intervalMin) scheduleCardavUser(req.session.userId, patch.intervalMin);
if (patch.password) requestCarddavSync(req.session.userId, config.connectionGeneration);
- res.json(publicStatus(config));
+ // Turning the setting on widens the export sweep, so publish the contacts it
+ // now admits instead of leaving the user waiting for the next interval tick.
+ // Like a book-role patch, it leaves the connection generation untouched, so a
+ // sync already in flight may have read the old value and be past the sweep:
+ // queue an uncoalesced follow-up rather than trusting it to have seen this.
+ // Turning it off needs no sync — it publishes nothing new, and contacts already
+ // in the address book stay there.
+ if (patch.publishEmailedContacts === true) {
+ requestCarddavSync(req.session.userId, config.connectionGeneration, { coalesce: false });
+ }
+ res.json(await publicStatus(config, req.session.userId));
+});
+
+// Map a book role-change failure to an HTTP status. A generation fence miss or
+// a disconnected connection is a 409 (the connection changed under the client);
+// a missing book is 404; a create-denied write-target attempt is 403; an empty
+// patch is 400. Anything else propagates to the 500 handler.
+function bookPatchError(res, err) {
+ if (err instanceof StaleCarddavPlanError) {
+ return res.status(409).json({ error: err.message, code: err.reason });
+ }
+ const status = {
+ ERR_CARDDAV_BOOK_PATCH_EMPTY: 400,
+ ERR_ADDRESS_BOOK_NOT_FOUND: 404,
+ ERR_CARDDAV_READ_ONLY: 403,
+ ERR_CARDDAV_WRITE_TARGET_SUBSCRIBED: 409,
+ }[err.code];
+ if (status) return res.status(status).json({ error: err.message, code: err.code });
+ throw err;
+}
+
+// Per-book role management: Subscribe / Look-up-senders toggles and the
+// write-target radio (see patchCarddavBookRoles). Fenced against the connection
+// generation the caller just read, then a background sync applies the pull-side
+// effects (a re-subscribed book materializes; an ignored book's ledger drops).
+// The role change leaves the generation untouched, so a sync already in flight
+// for it may be past the patched book: request an uncoalesced sync, which queues
+// a re-run behind that one instead of trusting it to have seen the change.
+router.patch('/books/:id', async (req, res) => {
+ const config = await getCardavConfig(req.session.userId);
+ if (!config?.serverUrl) return res.status(409).json({ error: 'CardDAV not connected' });
+ const { isSubscribed, isLookupSource, makeWriteTarget } = req.body || {};
+ try {
+ await patchCarddavBookRoles(
+ req.session.userId,
+ req.params.id,
+ { isSubscribed, isLookupSource, makeWriteTarget },
+ config.connectionGeneration,
+ );
+ } catch (err) {
+ return bookPatchError(res, err);
+ }
+ requestCarddavSync(req.session.userId, config.connectionGeneration, { coalesce: false });
+ res.json(await publicStatus(config, req.session.userId));
});
router.post('/sync', async (req, res) => {
const config = await getCardavConfig(req.session.userId);
if (!config?.serverUrl) return res.status(409).json({ error: 'CardDAV not connected' });
const result = await syncUser(req.session.userId);
- res.json({ ...result, status: publicStatus(await getCardavConfig(req.session.userId)) });
+ const status = await publicStatus(await getCardavConfig(req.session.userId), req.session.userId);
+ res.json({ ...result, status });
});
router.delete('/', async (req, res) => {
diff --git a/backend/src/routes/carddavAccount.test.js b/backend/src/routes/carddavAccount.test.js
index 9b3b20c..2329dad 100644
--- a/backend/src/routes/carddavAccount.test.js
+++ b/backend/src/routes/carddavAccount.test.js
@@ -1,10 +1,20 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
+class StaleCarddavPlanError extends Error {
+ constructor(details) {
+ super(details?.reason === 'not-connected' ? 'not connected' : 'CardDAV sync plan is stale');
+ this.name = 'StaleCarddavPlanError';
+ Object.assign(this, details);
+ }
+}
+
const mocks = vi.hoisted(() => ({
query: vi.fn(),
discoverAddressBooks: vi.fn(),
encrypt: vi.fn(value => `encrypted:${value}`),
getCardavConfig: vi.fn(),
+ getCarddavBookSummaries: vi.fn(),
+ patchCarddavBookRoles: vi.fn(),
replaceCarddavConnection: vi.fn(),
patchCarddavConnection: vi.fn(),
requestCarddavSync: vi.fn(),
@@ -25,12 +35,15 @@ vi.mock('../services/carddavClient.js', () => ({
}));
vi.mock('../services/carddavSync.js', () => ({
getCardavConfig: mocks.getCardavConfig,
+ getCarddavBookSummaries: mocks.getCarddavBookSummaries,
+ patchCarddavBookRoles: mocks.patchCarddavBookRoles,
replaceCarddavConnection: mocks.replaceCarddavConnection,
patchCarddavConnection: mocks.patchCarddavConnection,
requestCarddavSync: mocks.requestCarddavSync,
scheduleCardavUser: mocks.scheduleCardavUser,
syncUser: mocks.syncUser,
disconnectCarddavAccount: mocks.disconnectCarddavAccount,
+ StaleCarddavPlanError,
}));
const { default: router } = await import('./carddavAccount.js');
@@ -43,6 +56,9 @@ const patchHandler = router.stack
const syncHandler = router.stack
.find(layer => layer.route?.path === '/sync' && layer.route.methods.post)
.route.stack.at(-1).handle;
+const patchBookHandler = router.stack
+ .find(layer => layer.route?.path === '/books/:id' && layer.route.methods.patch)
+ .route.stack.at(-1).handle;
const deleteHandler = router.stack
.find(layer => layer.route?.path === '/' && layer.route.methods.delete)
.route.stack.at(-1).handle;
@@ -66,6 +82,7 @@ describe('POST /api/carddav/connect', () => {
lastError: null,
});
mocks.requestCarddavSync.mockReturnValue(true);
+ mocks.getCarddavBookSummaries.mockResolvedValue([]);
});
it('delegates replacement atomically and requests its committed generation', async () => {
@@ -93,13 +110,44 @@ describe('POST /api/carddav/connect', () => {
expect(mocks.replaceCarddavConnection.mock.invocationCallOrder[0])
.toBeLessThan(mocks.requestCarddavSync.mock.invocationCallOrder[0]);
expect(mocks.scheduleCardavUser).toHaveBeenCalledWith('user-1', 30);
+ expect(mocks.getCarddavBookSummaries).toHaveBeenCalledWith('user-1');
expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
connected: true,
+ books: [],
}));
expect(res.json.mock.calls[0][0]).not.toHaveProperty('dupMode');
expect(res.json.mock.calls[0][0]).not.toHaveProperty('connectionGeneration');
});
+ it('surfaces the per-book summary returned by the sync layer', async () => {
+ const books = [{
+ id: 'book-1',
+ name: 'Personal',
+ externalUrl: 'https://dav.example.test/books/personal',
+ isWriteTarget: true,
+ isSubscribed: true,
+ isLookupSource: true,
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ materializedCount: 3,
+ lookupCount: 0,
+ lastSyncAt: '2026-07-12T00:00:00.000Z',
+ }];
+ mocks.getCarddavBookSummaries.mockResolvedValueOnce(books);
+ const res = response();
+
+ await connectHandler({
+ session: { userId: 'user-1' },
+ body: {
+ serverUrl: 'https://dav.example.test/',
+ username: 'user',
+ password: 'secret',
+ intervalMin: 30,
+ },
+ }, res);
+
+ expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ books }));
+ });
+
it('does not request a sync when replacement persistence fails', async () => {
mocks.replaceCarddavConnection.mockRejectedValueOnce(new Error('replace failed'));
const res = response();
@@ -137,6 +185,7 @@ describe('PATCH /api/carddav', () => {
connectionGeneration: 'generation-a',
});
mocks.requestCarddavSync.mockReturnValue(true);
+ mocks.getCarddavBookSummaries.mockResolvedValue([]);
});
it('ignores obsolete duplicate-mode input while delegating the interval', async () => {
@@ -227,6 +276,7 @@ describe('POST /api/carddav/sync', () => {
bookCount: 1,
contactCount: 2,
});
+ mocks.getCarddavBookSummaries.mockResolvedValue([]);
});
it('preserves the result-plus-status envelope while exposing counters', async () => {
@@ -256,6 +306,100 @@ describe('POST /api/carddav/sync', () => {
});
});
+describe('PATCH /api/carddav/books/:id', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.getCardavConfig.mockResolvedValue({
+ serverUrl: 'https://dav.example.test/',
+ username: 'user',
+ connectionGeneration: 'generation-a',
+ });
+ mocks.patchCarddavBookRoles.mockResolvedValue('book-1');
+ mocks.requestCarddavSync.mockReturnValue(true);
+ mocks.getCarddavBookSummaries.mockResolvedValue([]);
+ });
+
+ it('delegates the role change fenced by generation, then syncs and returns the summary', async () => {
+ const books = [{ id: 'book-1', name: 'Primary', isWriteTarget: true }];
+ mocks.getCarddavBookSummaries.mockResolvedValueOnce(books);
+ const res = response();
+
+ await patchBookHandler({
+ session: { userId: 'user-1' },
+ params: { id: 'book-1' },
+ body: { makeWriteTarget: true },
+ }, res);
+
+ expect(mocks.patchCarddavBookRoles).toHaveBeenCalledWith(
+ 'user-1',
+ 'book-1',
+ { isSubscribed: undefined, isLookupSource: undefined, makeWriteTarget: true },
+ 'generation-a',
+ );
+ // A role change carries no new generation, so a sync already in flight for that
+ // generation may be past the patched book: request one that cannot be coalesced away.
+ expect(mocks.requestCarddavSync)
+ .toHaveBeenCalledWith('user-1', 'generation-a', { coalesce: false });
+ expect(mocks.patchCarddavBookRoles.mock.invocationCallOrder[0])
+ .toBeLessThan(mocks.requestCarddavSync.mock.invocationCallOrder[0]);
+ expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ connected: true, books }));
+ });
+
+ it('rejects with 409 when CardDAV is not connected and never mutates or syncs', async () => {
+ mocks.getCardavConfig.mockResolvedValueOnce(null);
+ const res = response();
+
+ await patchBookHandler({
+ session: { userId: 'user-1' },
+ params: { id: 'book-1' },
+ body: { isSubscribed: true },
+ }, res);
+
+ expect(res.status).toHaveBeenCalledWith(409);
+ expect(mocks.patchCarddavBookRoles).not.toHaveBeenCalled();
+ expect(mocks.requestCarddavSync).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ ['ERR_CARDDAV_READ_ONLY', 403],
+ ['ERR_CARDDAV_WRITE_TARGET_SUBSCRIBED', 409],
+ ['ERR_ADDRESS_BOOK_NOT_FOUND', 404],
+ ['ERR_CARDDAV_BOOK_PATCH_EMPTY', 400],
+ ])('maps %s to HTTP %i without triggering a sync', async (code, status) => {
+ mocks.patchCarddavBookRoles.mockRejectedValueOnce(Object.assign(new Error('nope'), { code }));
+ const res = response();
+
+ await patchBookHandler({
+ session: { userId: 'user-1' },
+ params: { id: 'book-1' },
+ body: { makeWriteTarget: true },
+ }, res);
+
+ expect(res.status).toHaveBeenCalledWith(status);
+ expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ code }));
+ expect(mocks.requestCarddavSync).not.toHaveBeenCalled();
+ });
+
+ it('maps a stale-generation fence to HTTP 409', async () => {
+ mocks.patchCarddavBookRoles.mockRejectedValueOnce(
+ new StaleCarddavPlanError({ reason: 'connection-generation-changed' }),
+ );
+ const res = response();
+
+ await patchBookHandler({
+ session: { userId: 'user-1' },
+ params: { id: 'book-1' },
+ body: { isSubscribed: false },
+ }, res);
+
+ expect(res.status).toHaveBeenCalledWith(409);
+ expect(res.json).toHaveBeenCalledWith(
+ expect.objectContaining({ code: 'connection-generation-changed' }),
+ );
+ expect(mocks.requestCarddavSync).not.toHaveBeenCalled();
+ });
+});
+
describe('DELETE /api/carddav', () => {
beforeEach(() => {
vi.clearAllMocks();
diff --git a/backend/src/routes/carddavConflicts.js b/backend/src/routes/carddavConflicts.js
index ed168c1..c9c3b7d 100644
--- a/backend/src/routes/carddavConflicts.js
+++ b/backend/src/routes/carddavConflicts.js
@@ -15,6 +15,7 @@ function conflictError(res, error) {
ERR_CARDDAV_CONFLICT_RESOLUTION: 400,
ERR_CARDDAV_CONFLICT_NOT_FOUND: 404,
ERR_CARDDAV_CONFLICT_STALE: 409,
+ ERR_CARDDAV_READ_ONLY: 403,
}[error.code];
if (status) return res.status(status).json({ error: error.message });
throw error;
diff --git a/backend/src/routes/contacts.js b/backend/src/routes/contacts.js
index 15dc71c..8056092 100644
--- a/backend/src/routes/contacts.js
+++ b/backend/src/routes/contacts.js
@@ -5,8 +5,10 @@ import {
CARDDAV_CONTACT_ERROR_STATUS,
createContact,
deleteContact,
+ promoteContact,
updateContact,
} from '../services/carddavContactService.js';
+import { resolveLookupPhoto } from '../services/carddavLookupService.js';
const router = Router();
router.use(requireAuth);
@@ -79,13 +81,16 @@ function contactError(res, err, fallback) {
return res.status(CARDDAV_CONTACT_ERROR_STATUS[err.code])
.json({ error: err.message, code: err.code, refresh: true });
}
+ // The code rides along with the message so a client can translate the states
+ // it can act on (no write-target, read-only book) instead of echoing a raw
+ // English message into a localized UI.
if (err.code === '23505') {
return res.status(CARDDAV_CONTACT_ERROR_STATUS[err.code])
.json({ error: 'A contact with that email already exists' });
}
const status = CARDDAV_CONTACT_ERROR_STATUS[err.code]
?? (Number.isInteger(err.status) ? err.status : null);
- if (status) return res.status(status).json({ error: err.message });
+ if (status) return res.status(status).json({ error: err.message, code: err.code });
console.error(`${fallback}:`, err);
return res.status(500).json({ error: fallback });
}
@@ -170,7 +175,18 @@ router.get('/photo', async (req, res) => {
[userId, email.trim()]
);
- if (!result.rows.length) return res.status(404).end();
+ // Ledger fallback: a sender materialized in no contacts row may still live in
+ // a lookup-only CardDAV book, whose retained vCard PHOTO is decoded lazily.
+ // Contacts-table photos are resolved first, so they always win.
+ if (!result.rows.length) {
+ const lookup = await resolveLookupPhoto(userId, email);
+ if (lookup) {
+ res.set('Cache-Control', 'private, max-age=86400');
+ res.set('Content-Type', lookup.mime);
+ return res.send(lookup.bytes);
+ }
+ return res.status(404).end();
+ }
const photoData = result.rows[0].photo_data;
res.set('Cache-Control', 'private, max-age=86400');
@@ -246,6 +262,20 @@ router.patch('/:id', async (req, res) => {
}
});
+// POST /api/contacts/:id/promote
+// Make an auto-collected contact explicit and export it to the CardDAV
+// write-target book right away. Editing a harvested contact deliberately does
+// not do this (see updateStoredContact) — publishing a sender to a shared
+// address book is a one-way action the user takes on purpose, never a side
+// effect of tidying up a field.
+router.post('/:id/promote', async (req, res) => {
+ try {
+ res.json(await promoteContact(req.session.userId, req.params.id));
+ } catch (err) {
+ contactError(res, err, 'Failed to save contact to the address book');
+ }
+});
+
// DELETE /api/contacts/:id
router.delete('/:id', async (req, res) => {
const userId = req.session.userId;
diff --git a/backend/src/routes/contacts.test.js b/backend/src/routes/contacts.test.js
index e13c183..16008bc 100644
--- a/backend/src/routes/contacts.test.js
+++ b/backend/src/routes/contacts.test.js
@@ -5,6 +5,8 @@ const mocks = vi.hoisted(() => ({
createContact: vi.fn(),
updateContact: vi.fn(),
deleteContact: vi.fn(),
+ promoteContact: vi.fn(),
+ resolveLookupPhoto: vi.fn(),
}));
vi.mock('../services/db.js', () => ({ query: mocks.query }));
@@ -22,11 +24,18 @@ vi.mock('../services/carddavContactService.js', () => ({
ERR_CARDDAV_AMBIGUOUS_WRITE: 409,
ERR_CARDDAV_PENDING_INTENT: 409,
ERR_CARDDAV_READ_ONLY: 403,
+ ERR_CARDDAV_NO_WRITE_TARGET: 409,
+ ERR_CARDDAV_NOT_CONNECTED: 409,
+ ERR_CARDDAV_ALREADY_MAPPED: 409,
'23505': 409,
},
createContact: mocks.createContact,
updateContact: mocks.updateContact,
deleteContact: mocks.deleteContact,
+ promoteContact: mocks.promoteContact,
+}));
+vi.mock('../services/carddavLookupService.js', () => ({
+ resolveLookupPhoto: mocks.resolveLookupPhoto,
}));
const { default: router } = await import('./contacts.js');
@@ -39,9 +48,11 @@ function handler(method, path) {
const listHandler = handler('get', '/');
const getHandler = handler('get', '/:id');
+const photoHandler = handler('get', '/photo');
const createHandler = handler('post', '/');
const updateHandler = handler('patch', '/:id');
const deleteHandler = handler('delete', '/:id');
+const promoteHandler = handler('post', '/:id/promote');
function response() {
return {
@@ -50,6 +61,18 @@ function response() {
};
}
+function photoResponse() {
+ const res = {
+ headers: {},
+ statusCode: 200,
+ set: vi.fn((key, value) => { res.headers[key] = value; return res; }),
+ status: vi.fn(code => { res.statusCode = code; return res; }),
+ send: vi.fn(() => res),
+ end: vi.fn(() => res),
+ };
+ return res;
+}
+
function draft(overrides = {}) {
return {
displayName: 'Ada Lovelace',
@@ -124,6 +147,45 @@ describe('contact read routes', () => {
});
});
+describe('GET /api/contacts/photo', () => {
+ it('serves a materialized contact photo without consulting the lookup ledger', async () => {
+ mocks.query.mockResolvedValueOnce({ rows: [{ photo_data: 'data:image/png;base64,AQID' }] });
+ const res = photoResponse();
+
+ await photoHandler({ session: { userId: 'user-1' }, query: { email: 'ada@example.test' } }, res);
+
+ expect(mocks.resolveLookupPhoto).not.toHaveBeenCalled();
+ expect(res.headers['Content-Type']).toBe('image/png');
+ expect(res.headers['Cache-Control']).toBe('private, max-age=86400');
+ expect(res.send).toHaveBeenCalledWith(Buffer.from('AQID', 'base64'));
+ });
+
+ it('falls back to a lookup-only book avatar on a contacts miss', async () => {
+ mocks.query.mockResolvedValueOnce({ rows: [] });
+ mocks.resolveLookupPhoto.mockResolvedValueOnce({ mime: 'image/jpeg', bytes: Buffer.from([1, 2, 3]) });
+ const res = photoResponse();
+
+ await photoHandler({ session: { userId: 'user-1' }, query: { email: 'sender@example.test' } }, res);
+
+ expect(mocks.resolveLookupPhoto).toHaveBeenCalledWith('user-1', 'sender@example.test');
+ expect(res.headers['Content-Type']).toBe('image/jpeg');
+ expect(res.headers['Cache-Control']).toBe('private, max-age=86400');
+ expect(res.send).toHaveBeenCalledWith(Buffer.from([1, 2, 3]));
+ expect(res.statusCode).toBe(200);
+ });
+
+ it('returns 404 when neither contacts nor a lookup book resolves the sender', async () => {
+ mocks.query.mockResolvedValueOnce({ rows: [] });
+ mocks.resolveLookupPhoto.mockResolvedValueOnce(null);
+ const res = photoResponse();
+
+ await photoHandler({ session: { userId: 'user-1' }, query: { email: 'nobody@example.test' } }, res);
+
+ expect(res.status).toHaveBeenCalledWith(404);
+ expect(res.send).not.toHaveBeenCalled();
+ });
+});
+
describe('POST /api/contacts', () => {
it('delegates exactly once and preserves local-only response behavior', async () => {
const body = draft();
@@ -140,6 +202,22 @@ describe('POST /api/contacts', () => {
expect(res.json).toHaveBeenCalledWith(created);
});
+ it('returns 409 with an actionable message when no write-target book is configured', async () => {
+ mocks.createContact.mockRejectedValueOnce(Object.assign(
+ new Error('No CardDAV write-target address book is configured'),
+ { code: 'ERR_CARDDAV_NO_WRITE_TARGET' },
+ ));
+ const res = response();
+
+ await createHandler({ session: { userId: 'user-1' }, body: draft() }, res);
+
+ expect(res.status).toHaveBeenCalledWith(409);
+ expect(res.json).toHaveBeenCalledWith({
+ error: 'No CardDAV write-target address book is configured',
+ code: 'ERR_CARDDAV_NO_WRITE_TARGET',
+ });
+ });
+
it.each([
['emails', draft({ emails: 'not-an-array' }), 'emails must be an array'],
['phones', draft({ phones: 'not-an-array' }), 'phones must be an array'],
@@ -188,7 +266,10 @@ describe('PATCH /api/contacts/:id', () => {
expect(mocks.updateContact).toHaveBeenCalledTimes(1);
expect(res.status).toHaveBeenCalledWith(403);
- expect(res.json).toHaveBeenCalledWith({ error: 'This CardDAV address book does not allow update' });
+ expect(res.json).toHaveBeenCalledWith({
+ error: 'This CardDAV address book does not allow update',
+ code: 'ERR_CARDDAV_READ_ONLY',
+ });
});
it('attempts an unknown-capability operation and reports its upstream denial', async () => {
@@ -317,3 +398,35 @@ describe('DELETE /api/contacts/:id', () => {
expect(res.json.mock.calls[0][0]).not.toHaveProperty('retriable', true);
});
});
+
+describe('POST /api/contacts/:id/promote', () => {
+ it('delegates the promotion exactly once and returns the promoted contact', async () => {
+ const promoted = { id: 'contact-1', display_name: 'Ada Lovelace', is_auto: false };
+ mocks.promoteContact.mockResolvedValueOnce(promoted);
+ const res = response();
+
+ await promoteHandler({ session: { userId: 'user-1' }, params: { id: 'contact-1' } }, res);
+
+ expect(mocks.promoteContact).toHaveBeenCalledTimes(1);
+ expect(mocks.promoteContact).toHaveBeenCalledWith('user-1', 'contact-1');
+ expect(mocks.query).not.toHaveBeenCalled();
+ expect(res.json).toHaveBeenCalledWith(promoted);
+ });
+
+ // The codes the promote affordance translates into actionable copy, rather
+ // than echoing a raw English backend message into a localized UI.
+ it.each([
+ ['ERR_CARDDAV_NO_WRITE_TARGET', 409],
+ ['ERR_CARDDAV_READ_ONLY', 403],
+ ['ERR_CARDDAV_NOT_CONNECTED', 409],
+ ['ERR_CARDDAV_ALREADY_MAPPED', 409],
+ ])('surfaces %s as a typed HTTP %i the client can act on', async (code, status) => {
+ mocks.promoteContact.mockRejectedValueOnce(Object.assign(new Error('Promotion failed'), { code }));
+ const res = response();
+
+ await promoteHandler({ session: { userId: 'user-1' }, params: { id: 'contact-1' } }, res);
+
+ expect(res.status).toHaveBeenCalledWith(status);
+ expect(res.json).toHaveBeenCalledWith({ error: 'Promotion failed', code });
+ });
+});
diff --git a/backend/src/services/carddavConflictService.js b/backend/src/services/carddavConflictService.js
index a2957c7..bfca226 100644
--- a/backend/src/services/carddavConflictService.js
+++ b/backend/src/services/carddavConflictService.js
@@ -103,13 +103,14 @@ export async function getConflict(userId, id) {
return row ? publicConflict(row) : null;
}
-function resolutionStateSql(lock = false) {
+function resolutionStateSql(lock = false, includeWriteTarget = false) {
const mappingJoin = lock ? 'JOIN' : 'LEFT JOIN';
return `SELECT conflict.*, mapping.mapping_revision::text, mapping.mapping_status,
contact.id AS contact_id, contact.uid AS contact_uid,
contact.etag AS contact_etag,
contact.address_book_id AS local_address_book_id,
remote_book.external_url AS remote_book_url,
+ ${includeWriteTarget ? 'remote_book.is_write_target AS remote_book_is_write_target,' : ''}
integration.config,
integration.config->>'connectionGeneration' AS connection_generation
FROM carddav_conflicts conflict
@@ -130,12 +131,32 @@ function resolutionStateSql(lock = false) {
${lock ? 'FOR UPDATE OF conflict, mapping, integration' : ''}`;
}
+// The write-target flag is only ever read by the unlocked pre-check
+// (resolveConflict, before any lock or transaction is open) to decide whether
+// a 'keep-mailflow' resolution may push to the remote resource at all — the
+// locked re-reads inside commitResolution/refreshConflictAfter412 persist an
+// already-decided outcome and never need it. Keeping it out of the locked
+// query also means it never needs a not-yet-migrated (transitional) schema
+// fallback: that query's shape doesn't change.
async function readResolutionState(executor, userId, id, lock = false) {
- const { rows: [state] } = await executor.query(
- resolutionStateSql(lock),
- [userId, id],
- );
- return state || null;
+ if (lock) {
+ const { rows: [state] } = await executor.query(resolutionStateSql(true), [userId, id]);
+ return state || null;
+ }
+ try {
+ const { rows: [state] } = await executor.query(
+ resolutionStateSql(false, true),
+ [userId, id],
+ );
+ return state || null;
+ } catch (error) {
+ if (error?.code !== '42703') throw error;
+ const { rows: [state] } = await executor.query(
+ resolutionStateSql(false, false),
+ [userId, id],
+ );
+ return state || null;
+ }
}
function staleConflict(id) {
@@ -347,6 +368,21 @@ export async function resolveConflict(userId, id, resolution) {
return commitResolution(userId, preflight, resolution, remote);
}
+ // 'keep-mailflow' pushes the local side to the remote resource — the one
+ // MailFlow-originated write this function performs. A subscribed or lookup
+ // book is read-only from MailFlow regardless of server write capability
+ // (multi-book-design.md's load-bearing invariant), so refuse before any
+ // network call when this conflict's book isn't the write-target.
+ // `remote_book_is_write_target` is only ever `false` (never absent) when the
+ // schema was actually queried; on a not-yet-migrated (transitional) schema
+ // the column is omitted entirely and this check is skipped.
+ if (preflight.remote_book_is_write_target === false) {
+ throw typedError(
+ 'This CardDAV address book is not the write-target; keep-MailFlow cannot push to it',
+ 'ERR_CARDDAV_READ_ONLY',
+ );
+ }
+
const latest = await fetchLatestRemote(preflight, creds);
try {
if (preflight.local_tombstone) {
diff --git a/backend/src/services/carddavConflictService.test.js b/backend/src/services/carddavConflictService.test.js
index d196450..582efda 100644
--- a/backend/src/services/carddavConflictService.test.js
+++ b/backend/src/services/carddavConflictService.test.js
@@ -91,6 +91,7 @@ function resolutionRow(overrides = {}) {
contact_etag: 'local-etag-before',
local_address_book_id: LOCAL_BOOK_ID,
remote_book_url: 'https://dav.example.test/books/default/',
+ remote_book_is_write_target: true,
connection_generation: 'generation-current',
config: {
serverUrl: 'https://dav.example.test/',
@@ -353,6 +354,44 @@ describe('conflict resolution lifecycle', () => {
expect(sql.some(statement => /UPDATE carddav_conflicts/.test(statement))).toBe(true);
});
+ // multi-book-design.md's load-bearing invariant: a subscribed (or lookup)
+ // secondary is read-only from MailFlow regardless of server write
+ // capability, so 'keep-mailflow' — the one MailFlow-originated write this
+ // service performs — must refuse before any network call when this
+ // conflict's book isn't the write-target.
+ it('refuses keep-mailflow before any network call when the book is not the write-target', async () => {
+ const preflight = resolutionRow({ remote_book_is_write_target: false });
+ mocks.query.mockResolvedValueOnce({ rows: [preflight] });
+
+ await expect(conflictService.resolveConflict(
+ USER_ID,
+ CONFLICT_ID,
+ 'keep-mailflow',
+ )).rejects.toMatchObject({ code: 'ERR_CARDDAV_READ_ONLY' });
+
+ expect(mocks.fetchCardResource).not.toHaveBeenCalled();
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ expect(mocks.deleteCardResource).not.toHaveBeenCalled();
+ expect(mocks.withTransaction).not.toHaveBeenCalled();
+ });
+
+ it('allows keep-carddav regardless of write-target status (no MailFlow-originated write)', async () => {
+ const preflight = resolutionRow({ remote_book_is_write_target: false });
+ const client = resolutionClient(preflight);
+ mocks.query.mockResolvedValueOnce({ rows: [preflight] });
+ mocks.fetchCardResource.mockResolvedValueOnce({ href: HREF, etag: '"remote-1"', vcard: remoteVCard });
+ mocks.withTransaction.mockImplementationOnce(async callback => callback(client));
+
+ await expect(conflictService.resolveConflict(
+ USER_ID,
+ CONFLICT_ID,
+ 'keep-carddav',
+ )).resolves.toMatchObject({ status: 'resolved', resolution: 'keep-carddav' });
+
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ expect(mocks.deleteCardResource).not.toHaveBeenCalled();
+ });
+
it('keep-mailflow conditionally deletes a local tombstone before canonical confirmation', async () => {
const preflight = resolutionRow({
local_vcard: null,
diff --git a/backend/src/services/carddavContactService.integration.test.js b/backend/src/services/carddavContactService.integration.test.js
index 24a1715..96285e6 100644
--- a/backend/src/services/carddavContactService.integration.test.js
+++ b/backend/src/services/carddavContactService.integration.test.js
@@ -229,7 +229,32 @@ async function seedConnectedUser(fixture) {
return { userId, connectionGeneration, localBookId: localBook.id };
}
-async function seedMappedContact(fixture, name = 'Mapped Before') {
+// Write-target routing (multi-book Slice 2) resolves the stored is_write_target
+// book against a *fresh* discovery snapshot; nothing yet assigns that flag to a
+// newly discovered book (that bootstrap is out of this slice's scope — see
+// Slice 3/5 of the multi-book design), so a brand-new fixture connection must
+// have its single book pre-designated the write target, exactly as Slice 1's
+// migration backfill does for an already-connected single-book user.
+async function seedWriteTargetBook(fixture, userId) {
+ const externalUrl = new URL('/addressbooks/fixture-user/contacts/', fixture.serverUrl).href;
+ await databaseClient.query(`
+ INSERT INTO address_books (
+ user_id, name, source, external_url,
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed', true, true, true)
+ `, [userId, externalUrl]);
+ return externalUrl;
+}
+
+// `isWriteTarget` defaults to true: these fixtures back tests of pending-intent,
+// conflict, and throttle *mechanics*, not the write-target invariant itself, so
+// they seed a mapped contact whose book is the write target — mirroring what
+// Slice 1's migration backfill (or a real first-sync auto-assignment) already
+// established for an already-connected single-book user. A dedicated test
+// below covers `isWriteTarget: false` (a subscribed secondary) to prove the
+// invariant that a non-write-target book never receives a PUT/DELETE.
+async function seedMappedContact(fixture, name = 'Mapped Before', { isWriteTarget = true } = {}) {
const seeded = await seedConnectedUser(fixture);
const uid = randomUUID();
const rawVCard = vcard(uid, name);
@@ -238,10 +263,15 @@ async function seedMappedContact(fixture, name = 'Mapped Before') {
const { rows: [remoteBook] } = await databaseClient.query(`
INSERT INTO address_books (
user_id, name, source, external_url,
- remote_create_capability, remote_update_capability, remote_delete_capability
- ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed')
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed', $3, true, true)
RETURNING id
- `, [seeded.userId, new URL('/addressbooks/fixture-user/contacts/', fixture.serverUrl).href]);
+ `, [
+ seeded.userId,
+ new URL('/addressbooks/fixture-user/contacts/', fixture.serverUrl).href,
+ isWriteTarget,
+ ]);
const { rows: [contact] } = await databaseClient.query(`
INSERT INTO contacts (
address_book_id, user_id, uid, vcard, etag, display_name,
@@ -276,6 +306,49 @@ async function seedMappedContact(fixture, name = 'Mapped Before') {
return { ...seeded, uid, href, remoteEtag, remoteBookId: remoteBook.id, contact };
}
+// A sender harvested from an inbound message: an unmapped `is_auto` contacts row
+// in the user's local book, exactly as imapManager's collector leaves it. The
+// carddav book is seeded create-capable either way, so only its is_write_target
+// flag decides whether promotion has a destination.
+async function seedAutoContact(fixture, {
+ displayName = 'Harvested Sender',
+ isWriteTarget = true,
+} = {}) {
+ const seeded = await seedConnectedUser(fixture);
+ const { rows: [remoteBook] } = await databaseClient.query(`
+ INSERT INTO address_books (
+ user_id, name, source, external_url,
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed', $3, true, true)
+ RETURNING id
+ `, [
+ seeded.userId,
+ new URL('/addressbooks/fixture-user/contacts/', fixture.serverUrl).href,
+ isWriteTarget,
+ ]);
+ const uid = randomUUID();
+ const email = `${uid}@example.test`;
+ const rawVCard = vcard(uid, displayName, email);
+ const { rows: [contact] } = await databaseClient.query(`
+ INSERT INTO contacts (
+ address_book_id, user_id, uid, vcard, etag, display_name,
+ primary_email, emails, phones, additional_fields, is_auto
+ ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,'[]'::jsonb,'[]'::jsonb,true)
+ RETURNING id, etag
+ `, [
+ seeded.localBookId,
+ seeded.userId,
+ uid,
+ rawVCard,
+ createHash('md5').update(rawVCard).digest('hex'),
+ displayName,
+ email,
+ JSON.stringify([{ value: email, type: 'other', primary: true }]),
+ ]);
+ return { ...seeded, uid, email, remoteBookId: remoteBook.id, contact };
+}
+
// Reproduce the state a sync pull leaves behind: the local contacts row holds the
// LOSSY re-serialized vCard (generateVCard drops unmodeled properties) while the
// carddav_remote_objects row retains the FULL remote vCard. The local UID is the
@@ -298,8 +371,9 @@ async function seedImportedContact(fixture, remoteVCard, remoteEtag = '"imported
const { rows: [remoteBook] } = await databaseClient.query(`
INSERT INTO address_books (
user_id, name, source, external_url,
- remote_create_capability, remote_update_capability, remote_delete_capability
- ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed')
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed', true, true, true)
RETURNING id
`, [seeded.userId, new URL('/addressbooks/fixture-user/contacts/', fixture.serverUrl).href]);
const { rows: [contact] } = await databaseClient.query(`
@@ -461,6 +535,7 @@ describe('CardDAV contact mutations against PostgreSQL 16 and HTTP', () => {
const fixture = createCarddavFixtureServer();
await fixture.listen();
const { userId, localBookId } = await seedConnectedUser(fixture);
+ await seedWriteTargetBook(fixture, userId);
const uid = randomUUID();
try {
@@ -570,10 +645,220 @@ describe('CardDAV contact mutations against PostgreSQL 16 and HTTP', () => {
}
}, 120_000);
+ // carddavSync.js's canonical-URL reconciliation (advanceDiscoveredBookState)
+ // rewrites a book's external_url to the canonical URL a redirect resolves
+ // to, but records the alias it replaced in discovery_alias_url — because
+ // the server keeps advertising that alias in PROPFIND discovery forever
+ // afterward. selectedCreateBook matches the write-target by either URL, so
+ // an interactive create discovers and PUTs through the alias; persisting
+ // that discovered book must resolve back to the *existing* write-target
+ // row (by discovery_alias_url), never insert a second, non-write-target
+ // row for the same remote collection.
+ it('routes a create through the discovery alias into the existing write-target row, never a duplicate', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const { userId, localBookId } = await seedConnectedUser(fixture);
+ const canonicalUrl = new URL('/addressbooks/fixture-user/canonical/', fixture.serverUrl).href;
+ const aliasUrl = new URL('/addressbooks/fixture-user/alias/', fixture.serverUrl).href;
+ const { rows: [writeTargetBook] } = await databaseClient.query(`
+ INSERT INTO address_books (
+ user_id, name, source, external_url, discovery_alias_url,
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, $3, 'allowed', 'allowed', 'allowed', true, true, true)
+ RETURNING id
+ `, [userId, canonicalUrl, aliasUrl]);
+ const uid = randomUUID();
+
+ try {
+ resetObservation(fixture);
+ fixture.queueDiscovery({ books: [{ href: '/addressbooks/fixture-user/alias/', displayName: 'Alias Book' }] });
+ const created = await contactService.createContactFromVCard(userId, {
+ localAddressBookId: localBookId,
+ uid,
+ rawVCard: vcard(uid, 'Alias Routed Create'),
+ });
+
+ const { rows: books } = await databaseClient.query(`
+ SELECT id, external_url, discovery_alias_url, is_write_target,
+ remote_update_capability
+ FROM address_books
+ WHERE user_id = $1 AND source = 'carddav'
+ `, [userId]);
+ // Still exactly one carddav book — the pre-existing write-target row,
+ // untouched — never a second, non-write-target row for the alias URL.
+ expect(books).toEqual([{
+ id: writeTargetBook.id,
+ external_url: canonicalUrl,
+ discovery_alias_url: aliasUrl,
+ is_write_target: true,
+ remote_update_capability: 'allowed',
+ }]);
+ const afterCreate = await authoritativeState(userId);
+ // Mapped into that same write-target row: assertWritable's
+ // mapping_is_write_target check (carddavContactService.js) reads this
+ // join, so this contact is not stranded on a stray non-target
+ // duplicate that would reject every future update/delete as read-only.
+ expect(afterCreate.remoteObjects).toEqual([
+ expect.objectContaining({
+ address_book_id: writeTargetBook.id,
+ local_contact_id: created.id,
+ }),
+ ]);
+ expectNoNetworkInsideTransactions();
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
+ // multi-book-design.md, key decision 3: an incidental cleanup of a harvested
+ // sender must not publish it. The edit lands locally and the contact stays
+ // auto-collected, so the next sync's export sweep (which only claims
+ // is_auto = false contacts) still passes it over.
+ it('keeps an edited harvested contact auto-collected and writes nothing remote', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedAutoContact(fixture);
+
+ try {
+ resetObservation(fixture);
+ const updated = await contactService.updateContact(
+ seeded.userId,
+ seeded.contact.id,
+ { displayName: 'Harvested Renamed', organization: 'Tidied Up' },
+ );
+
+ expect(updated).toMatchObject({
+ id: seeded.contact.id,
+ display_name: 'Harvested Renamed',
+ organization: 'Tidied Up',
+ is_auto: true,
+ });
+ const after = await authoritativeState(seeded.userId);
+ expect(after.contacts).toEqual([
+ expect.objectContaining({ id: seeded.contact.id, is_auto: true }),
+ ]);
+ expect(after.remoteObjects).toEqual([]);
+ expect(fixture.counters.requests).toBe(0);
+ expectNoNetworkInsideTransactions();
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
+ // Promotion is the one deliberate action that makes a harvested contact
+ // explicit, and it lands in the designated write-target — never in the first
+ // create-capable book discovery happens to return (that was the wrong-book
+ // footgun). The local is_auto flip is remote-first: it commits only after the
+ // PUT is read back and confirmed.
+ it('promotes a harvested contact into the write-target book, never a sibling book', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedAutoContact(fixture, { isWriteTarget: false });
+ const writeTargetPath = '/addressbooks/fixture-user/shared/';
+ const writeTargetUrl = new URL(writeTargetPath, fixture.serverUrl).href;
+ const { rows: [writeTargetBook] } = await databaseClient.query(`
+ INSERT INTO address_books (
+ user_id, name, source, external_url,
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Shared Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed', true, true, true)
+ RETURNING id
+ `, [seeded.userId, writeTargetUrl]);
+
+ try {
+ resetObservation(fixture);
+ // Discovery returns the sibling book FIRST: only the stored write-target
+ // flag stands between this contact and the wrong book.
+ fixture.queueDiscovery({ books: [
+ { href: '/addressbooks/fixture-user/contacts/', displayName: 'Fixture Contacts' },
+ { href: writeTargetPath, displayName: 'Shared Contacts' },
+ ] });
+ const promoted = await contactService.promoteContact(seeded.userId, seeded.contact.id);
+
+ expect(promoted).toMatchObject({ id: seeded.contact.id, is_auto: false });
+ const put = fixture.requests.filter(request => request.method === 'PUT');
+ expect(put).toHaveLength(1);
+ expect(put[0].path).toBe(`${writeTargetPath}${seeded.uid}.vcf`);
+ expect(fixture.counters.create).toBe(1);
+
+ const after = await authoritativeState(seeded.userId);
+ expect(after.contacts).toEqual([
+ expect.objectContaining({ id: seeded.contact.id, is_auto: false }),
+ ]);
+ expect(after.remoteObjects).toEqual([
+ expect.objectContaining({
+ address_book_id: writeTargetBook.id,
+ href: new URL(`${seeded.uid}.vcf`, writeTargetUrl).href,
+ local_contact_id: seeded.contact.id,
+ mapping_status: 'synced',
+ }),
+ ]);
+ expect(after.conflicts).toEqual([]);
+ expectNoNetworkInsideTransactions();
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
+ // Promotion is the deliberate act that makes a harvested contact the user's own,
+ // so it records the publish intent the export sweep gates on. Without that the
+ // contact would be relying on the publish-emailed-contacts setting — OFF here,
+ // as it is by default — to stay in the address book it was just added to.
+ it('records publish intent when promoting, independently of the emailed-contacts setting', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedAutoContact(fixture);
+
+ try {
+ resetObservation(fixture);
+ const promoted = await contactService.promoteContact(seeded.userId, seeded.contact.id);
+
+ expect(promoted).toMatchObject({ id: seeded.contact.id, is_auto: false });
+ expect(fixture.requests.filter(request => request.method === 'PUT')).toHaveLength(1);
+
+ const { rows: [row] } = await databaseClient.query(
+ 'SELECT is_auto, carddav_publish_intent FROM contacts WHERE id = $1',
+ [seeded.contact.id],
+ );
+ expect(row).toEqual({ is_auto: false, carddav_publish_intent: true });
+ expectNoNetworkInsideTransactions();
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
+ // The book is fully create-capable on the server, so only the missing
+ // write-target designation refuses this promotion — no silent fallback to
+ // "some other writable book", and no local is_auto flip without a remote.
+ it('refuses to promote without a write-target and leaves the contact harvested', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedAutoContact(fixture, { isWriteTarget: false });
+
+ try {
+ resetObservation(fixture);
+ const before = await authoritativeState(seeded.userId);
+ fixture.queueDiscovery({ books: [
+ { href: '/addressbooks/fixture-user/contacts/', displayName: 'Fixture Contacts' },
+ ] });
+ await expect(contactService.promoteContact(seeded.userId, seeded.contact.id))
+ .rejects.toMatchObject({ code: 'ERR_CARDDAV_NO_WRITE_TARGET' });
+
+ expect(await authoritativeState(seeded.userId)).toEqual(before);
+ expect(fixture.counters.create).toBe(0);
+ expect(fixture.requests.some(request => request.method === 'PUT')).toBe(false);
+ expectNoNetworkInsideTransactions();
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
it('atomically resolves concurrent mapped create-only requests for one book and UID', async () => {
const fixture = createCarddavFixtureServer();
await fixture.listen();
const { userId, localBookId } = await seedConnectedUser(fixture);
+ await seedWriteTargetBook(fixture, userId);
const uid = randomUUID();
let preflightCommits = 0;
let releasePreflightCommits;
@@ -667,12 +952,35 @@ describe('CardDAV contact mutations against PostgreSQL 16 and HTTP', () => {
}
});
- // The recovery fetch after a 412 must reject a malformed or oversized REMOTE
- // snapshot before it can persist. (A replace now overlays the client body onto the
- // retained remote vCard, so the pending intent is bounded by the retained document
- // rather than the raw client body; the pending-intent 1 MiB and conflict-snapshot
- // 2 MiB size limits are unit-tested at their exact boundaries in
- // carddavMappingState.test.js.)
+ // A subscribed or lookup secondary stays read-only from MailFlow even when
+ // the remote server advertises full mutation capability.
+ it('never PUTs or DELETEs a contact mapped into a book that is not the write-target', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedMappedContact(fixture, 'Secondary Mapped', { isWriteTarget: false });
+
+ try {
+ resetObservation(fixture);
+ const before = await authoritativeState(seeded.userId);
+ await expect(contactService.updateContact(
+ seeded.userId,
+ seeded.contact.id,
+ draft('Rejected Secondary Edit', `${seeded.uid}@example.test`),
+ )).rejects.toMatchObject({ code: 'ERR_CARDDAV_READ_ONLY' });
+ expect(await authoritativeState(seeded.userId)).toEqual(before);
+ expect(fixture.counters.requests).toBe(0);
+
+ await expect(contactService.deleteContact(seeded.userId, seeded.contact.id))
+ .rejects.toMatchObject({ code: 'ERR_CARDDAV_READ_ONLY' });
+ expect(await authoritativeState(seeded.userId)).toEqual(before);
+ expect(fixture.counters.requests).toBe(0);
+ expectNoNetworkInsideTransactions();
+ } finally {
+ await fixture.close();
+ }
+ });
+ // The recovery fetch after a 412 must reject a malformed or oversized remote
+ // snapshot before it can persist.
it.each([
{
label: 'malformed remote snapshot',
@@ -1155,7 +1463,7 @@ describe('CardDAV contact mutations against PostgreSQL 16 and HTTP', () => {
}
}, 120_000);
- it('does not duplicate the modeled main when a mixed Apple item-group survives (W7)', async () => {
+ it('does not duplicate the modeled main when a mixed Apple item-group survives', async () => {
const fixture = createCarddavFixtureServer();
await fixture.listen();
try {
diff --git a/backend/src/services/carddavContactService.js b/backend/src/services/carddavContactService.js
index 9c07fcf..7f3c2ed 100644
--- a/backend/src/services/carddavContactService.js
+++ b/backend/src/services/carddavContactService.js
@@ -73,6 +73,9 @@ export const CARDDAV_CONTACT_ERROR_STATUS = Object.freeze({
ERR_CONTACT_EXISTS: 409,
ERR_CARDDAV_CONFLICT: 409,
ERR_CARDDAV_READ_ONLY: 403,
+ ERR_CARDDAV_NO_WRITE_TARGET: 409,
+ ERR_CARDDAV_NOT_CONNECTED: 409,
+ ERR_CARDDAV_ALREADY_MAPPED: 409,
ERR_CARDDAV_FINAL_FENCE: 503,
ERR_CARDDAV_STALE_GENERATION: 503,
ERR_CARDDAV_AMBIGUOUS_WRITE: 409,
@@ -247,7 +250,7 @@ function mergedReplacePayload(clientDocument, retainedDocument) {
continue;
}
// A grouped property survives iff the group has an unmodeled member whose name the client
- // omitted. Then the group survives, but W7: emit ONLY its unmodeled members and its
+ // omitted. Then the group survives, but emit ONLY its unmodeled members and its
// X-ABLABEL — NEVER a modeled main (ADR/URL/TEL/…) the client already owns via its
// full-state modeled fields, which would duplicate that property on the wire (the standard
// Apple item1.ADR + item1.X-ABADR + item1.X-ABLABEL layout). ACCEPTED CONSEQUENCE: a
@@ -303,10 +306,25 @@ function capability(contact, operation) {
return contact[`remote_${operation}_capability`] ?? 'unknown';
}
+// A mapped contact whose remote book is not the user's designated
+// is_write_target is a subscribed (or lookup) secondary: read-only from
+// MailFlow *regardless of server write capability* (multi-book-design.md's
+// load-bearing invariant). Every caller only reaches assertWritable for a
+// mapped contact (contact.href is truthy — see updateContact et al.), so an
+// unmapped contact's absent mapping_is_write_target (undefined, not `false`)
+// never trips this. Same for a not-yet-migrated (transitional) schema, where
+// readContact omits the column entirely — consistent with every book being
+// unrestricted before multi-book roles existed.
function assertWritable(contact, operation) {
if (capability(contact, operation) === 'denied') {
throw typedError(`This CardDAV address book does not allow ${operation}`, 'ERR_CARDDAV_READ_ONLY');
}
+ if (contact.mapping_is_write_target === false) {
+ throw typedError(
+ 'This CardDAV address book is not the write-target and cannot be modified',
+ 'ERR_CARDDAV_READ_ONLY',
+ );
+ }
if (contact.mapping_status === 'conflict' && contact.conflict_id) {
throw new CardDavConflictError(contact.conflict_id);
}
@@ -324,15 +342,8 @@ async function readIntegration(client, userId, lock = false) {
return integration?.config?.serverUrl ? integration : null;
}
-async function readContact(client, userId, { contactId, localAddressBookId, uid }) {
- const conditions = contactId
- ? 'c.id = $2'
- : 'c.address_book_id = $2 AND c.uid = $3';
- const params = contactId
- ? [userId, contactId]
- : [userId, localAddressBookId, uid];
- const { rows: [contact] } = await client.query(
- `SELECT c.*,
+function readContactSql(conditions, includeWriteTarget) {
+ return `SELECT c.*,
c.address_book_id AS local_address_book_id,
mapping.address_book_id AS mapping_address_book_id,
mapping.href, mapping.remote_etag, mapping.mapping_status,
@@ -346,6 +357,7 @@ async function readContact(client, userId, { contactId, localAddressBookId, uid
remote_book.remote_create_capability,
remote_book.remote_update_capability,
remote_book.remote_delete_capability,
+ ${includeWriteTarget ? 'remote_book.is_write_target AS mapping_is_write_target,' : ''}
conflict.id AS conflict_id
FROM contacts c
JOIN address_books local_book ON local_book.id = c.address_book_id
@@ -357,10 +369,36 @@ async function readContact(client, userId, { contactId, localAddressBookId, uid
ON conflict.address_book_id = mapping.address_book_id
AND conflict.href = mapping.href
AND conflict.status = 'unresolved'
- WHERE c.user_id = $1 AND ${conditions}`,
- params,
- );
- return contact || null;
+ WHERE c.user_id = $1 AND ${conditions}`;
+}
+
+// The write-target join is read on every mapped-contact mutation (see
+// assertWritable), so it's guarded the same way selectedCreateBook guards its
+// own is_write_target read: catch PostgreSQL's undefined_column SQLSTATE
+// (a not-yet-migrated, transitional schema) and retry without that column,
+// rather than a separate information_schema pre-check on every read. A
+// SAVEPOINT is required around the first attempt because this always runs
+// inside the caller's transaction — an uncaught undefined_column error would
+// otherwise abort that whole transaction, not just this query.
+async function readContact(client, userId, { contactId, localAddressBookId, uid }) {
+ const conditions = contactId
+ ? 'c.id = $2'
+ : 'c.address_book_id = $2 AND c.uid = $3';
+ const params = contactId
+ ? [userId, contactId]
+ : [userId, localAddressBookId, uid];
+ await client.query('SAVEPOINT carddav_read_contact');
+ try {
+ const { rows: [contact] } = await client.query(readContactSql(conditions, true), params);
+ await client.query('RELEASE SAVEPOINT carddav_read_contact');
+ return contact || null;
+ } catch (error) {
+ if (!isUndefinedColumn(error)) throw error;
+ await client.query('ROLLBACK TO SAVEPOINT carddav_read_contact');
+ await client.query('RELEASE SAVEPOINT carddav_read_contact');
+ const { rows: [contact] } = await client.query(readContactSql(conditions, false), params);
+ return contact || null;
+ }
}
async function readOwnedBook(client, userId, addressBookId) {
@@ -406,11 +444,68 @@ async function discoverCreateContext(userId, integration) {
}
}
-function selectedCreateBook(books) {
- if (!Array.isArray(books)) throw typedError('A fresh CardDAV book snapshot is required', 'ERR_CARDDAV_BOOKS');
- const selected = books.find(book => book.capabilities?.create === 'allowed')
+// PostgreSQL's undefined_column SQLSTATE — a not-yet-migrated (transitional,
+// mid-deploy) database that predates the multi-book columns. Detected by
+// catching the error rather than a separate information_schema pre-check (as
+// supportsPendingIntentSchema does) because this query runs on every single
+// write, not once per sync; a second round trip here is exactly the kind of
+// per-write latency this hot path can't absorb.
+function isUndefinedColumn(error) {
+ return error?.code === '42703';
+}
+
+// The single destination for every MailFlow-originated create/export/promotion:
+// the book the user designated `is_write_target`, resolved against a *fresh*
+// discovery snapshot by `external_url` (discovery may run seconds or days after
+// the book was last persisted). There is deliberately no fallback to a
+// different book — a missing or now-denied write-target is a typed, actionable
+// error, never a silent re-route to "some other writable book" (that was the
+// wrong-book footgun this replaces).
+async function writeTargetBookUrls(userId) {
+ const { rows: [target] } = await query(
+ `SELECT external_url, discovery_alias_url
+ FROM address_books
+ WHERE user_id = $1 AND source = 'carddav' AND is_write_target = true`,
+ [userId],
+ );
+ return target ? { externalUrl: target.external_url, aliasUrl: target.discovery_alias_url } : null;
+}
+
+function firstCapableBook(books) {
+ return books.find(book => book.capabilities?.create === 'allowed')
|| books.find(book => (book.capabilities?.create ?? 'unknown') === 'unknown');
- if (!selected) throw typedError('No writable CardDAV address book was discovered', 'ERR_CARDDAV_READ_ONLY');
+}
+
+async function selectedCreateBook(userId, books) {
+ if (!Array.isArray(books)) throw typedError('A fresh CardDAV book snapshot is required', 'ERR_CARDDAV_BOOKS');
+ let target;
+ try {
+ target = await writeTargetBookUrls(userId);
+ } catch (error) {
+ if (!isUndefinedColumn(error)) throw error;
+ const fallback = firstCapableBook(books);
+ if (!fallback) throw typedError('No writable CardDAV address book was discovered', 'ERR_CARDDAV_READ_ONLY');
+ return fallback;
+ }
+ if (!target) {
+ throw typedError('No CardDAV write-target address book is configured', 'ERR_CARDDAV_NO_WRITE_TARGET');
+ }
+ // Match by the stored canonical URL first, then by the discovery alias a
+ // redirect-reconciling server may still be advertising (see
+ // advanceDiscoveredBookState in carddavMappingState.js) — a fresh discovery
+ // snapshot can otherwise never re-find a book whose external_url sync
+ // already rewrote to a different canonical URL.
+ const selected = books.find(book => book.url === target.externalUrl)
+ || (target.aliasUrl && books.find(book => book.url === target.aliasUrl));
+ if (!selected) {
+ throw typedError(
+ 'The configured CardDAV write-target address book was not found on this server',
+ 'ERR_CARDDAV_NO_WRITE_TARGET',
+ );
+ }
+ if (selected.capabilities?.create === 'denied') {
+ throw typedError('The CardDAV write-target address book does not allow create', 'ERR_CARDDAV_READ_ONLY');
+ }
return selected;
}
@@ -474,6 +569,12 @@ export function contactValues(payload) {
];
}
+// A contact created through this service is one the user deliberately created, so
+// it carries publish intent: unlike a contact that became explicit merely by being
+// emailed, it belongs in the address book whatever publishEmailedContacts says.
+// This matters most for a contact created while CardDAV is disconnected —
+// connecting an account later sweeps it out, and the intent recorded here is what
+// lets it through.
export async function insertContact(client, userId, addressBookId, payload, {
returning = API_CONTACT_COLUMNS,
} = {}) {
@@ -481,8 +582,9 @@ export async function insertContact(client, userId, addressBookId, payload, {
`INSERT INTO contacts (
address_book_id, user_id, uid, vcard, etag,
display_name, first_name, last_name, primary_email,
- emails, phones, organization, notes, photo_data, additional_fields, is_auto
- ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb,$11::jsonb,$12,$13,$14,$15::jsonb,false)
+ emails, phones, organization, notes, photo_data, additional_fields, is_auto,
+ carddav_publish_intent
+ ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb,$11::jsonb,$12,$13,$14,$15::jsonb,false,true)
RETURNING ${returning}`,
[addressBookId, userId, ...contactValues(payload)],
);
@@ -494,24 +596,33 @@ function isLocalContactUidConflict(error) {
&& error.constraint === 'contacts_address_book_id_uid_key';
}
+// `markExplicit` clears is_auto and records publish intent — together, the flip
+// that makes a harvested contact a curated one the export sweep will keep in sync.
+// Only a *remote-confirmed* create sets it (see commitRemoteCreate): editing a
+// field of an auto-collected contact deliberately leaves it auto-collected, so an
+// incidental cleanup of a harvested sender never publishes it to the shared
+// write-target book (multi-book-design.md, key decision 3). Promotion is the one
+// deliberate path, and the intent it records is what keeps the contact published
+// no matter what the publishEmailedContacts setting is later set to.
export async function updateStoredContact(
client,
userId,
contactId,
payload,
expectedEtag = null,
- { returning = API_CONTACT_COLUMNS, onMissing = null } = {},
+ { returning = API_CONTACT_COLUMNS, onMissing = null, markExplicit = false } = {},
) {
const etagFence = expectedEtag == null ? '' : 'AND etag = $16';
const params = [...contactValues(payload), contactId, userId];
if (expectedEtag != null) params.push(expectedEtag);
+ const explicit = markExplicit ? ' is_auto = false, carddav_publish_intent = true,' : '';
const { rows: [row] } = await client.query(
`UPDATE contacts SET
uid = $1, vcard = $2, etag = $3,
display_name = $4, first_name = $5, last_name = $6,
primary_email = $7, emails = $8::jsonb, phones = $9::jsonb,
organization = $10, notes = $11, photo_data = $12,
- additional_fields = $13::jsonb, is_auto = false, updated_at = NOW()
+ additional_fields = $13::jsonb,${explicit} updated_at = NOW()
WHERE id = $14 AND user_id = $15 ${etagFence}
RETURNING ${returning}`,
params,
@@ -707,6 +818,10 @@ async function commitRemoteCreate({ userId, preflight, localAddressBookId, book,
}
const localBook = localAddressBookId ?? await ensureLocalBook(client, userId);
const remoteBook = await persistDiscoveredBook(client, { userId, ...book });
+ // The contact now exists in the write-target book, so it is explicit:
+ // an export of an already-explicit contact re-affirms the flag, and a
+ // promotion of a harvested one flips it — here, after the remote write
+ // is confirmed, never before.
const row = preflight.contactId
? await updateStoredContact(
client,
@@ -714,6 +829,7 @@ async function commitRemoteCreate({ userId, preflight, localAddressBookId, book,
preflight.contactId,
payload,
preflight.localEtag,
+ { markExplicit: true },
)
: await insertContact(client, userId, localBook, payload);
assertMappingApplied(await applyConfirmedRemoteContact(client, {
@@ -1277,7 +1393,7 @@ export async function createContact(userId, draft) {
return withTransaction(client => createLocal(client, userId, null, payload));
}
const { books, creds } = await discoverCreateContext(userId, preflight.integration);
- const selected = selectedCreateBook(books);
+ const selected = await selectedCreateBook(userId, books);
const payload = payloadForDraft(uid, validatedDraft, selectedVCardVersion(selected));
return remoteCreate({
userId,
@@ -1342,7 +1458,7 @@ export async function deleteContact(userId, contactId) {
}
export async function exportExistingContact(userId, contactId, { books, expectedGeneration }) {
- const selected = selectedCreateBook(books);
+ const selected = await selectedCreateBook(userId, books);
const prepared = await withTransaction(async client => {
const integration = await readIntegration(client, userId);
if (!integration) throw typedError('CardDAV is not connected', 'ERR_CARDDAV_NOT_CONNECTED');
@@ -1385,6 +1501,27 @@ export async function exportExistingContact(userId, contactId, { books, expected
});
}
+// The deliberate promotion of an auto-collected contact: make it explicit and
+// export it to the write-target book *now*, so the user gets direct feedback
+// instead of a silent next-sync side effect. It is a one-way action, not a
+// per-contact sync toggle — once explicit, the contact simply obeys the normal
+// "explicit contacts synchronize automatically" rule.
+//
+// Deliberately the same write path as the sweep's export (exportExistingContact),
+// so promotion inherits every invariant unchanged: write-target-only routing,
+// the Retry-After gate, the connection-generation fence, and the remote-first
+// commit whose ambiguous-write recovery re-reads the remote before touching
+// local state. The is_auto flip rides along in that confirmed commit.
+export async function promoteContact(userId, contactId) {
+ const integration = await withTransaction(client => readIntegration(client, userId));
+ if (!integration) throw typedError('CardDAV is not connected', 'ERR_CARDDAV_NOT_CONNECTED');
+ const { books } = await discoverCreateContext(userId, integration);
+ return exportExistingContact(userId, contactId, {
+ books,
+ expectedGeneration: integration.config.connectionGeneration ?? null,
+ });
+}
+
export async function createContactFromVCard(userId, {
localAddressBookId,
uid,
@@ -1422,7 +1559,7 @@ export async function createContactFromVCard(userId, {
});
if (prepared.local) return prepared.local;
const { books, creds } = await discoverCreateContext(userId, prepared.integration);
- const selected = selectedCreateBook(books);
+ const selected = await selectedCreateBook(userId, books);
return remoteCreate({
userId,
preflight: prepared,
diff --git a/backend/src/services/carddavContactService.test.js b/backend/src/services/carddavContactService.test.js
index 50bce3a..a71f52c 100644
--- a/backend/src/services/carddavContactService.test.js
+++ b/backend/src/services/carddavContactService.test.js
@@ -68,6 +68,9 @@ it('exports the shared CardDAV contact error status mappings', () => {
ERR_CONTACT_EXISTS: 409,
ERR_CARDDAV_CONFLICT: 409,
ERR_CARDDAV_READ_ONLY: 403,
+ ERR_CARDDAV_NO_WRITE_TARGET: 409,
+ ERR_CARDDAV_NOT_CONNECTED: 409,
+ ERR_CARDDAV_ALREADY_MAPPED: 409,
ERR_CARDDAV_FINAL_FENCE: 503,
ERR_CARDDAV_STALE_GENERATION: 503,
ERR_CARDDAV_AMBIGUOUS_WRITE: 409,
@@ -160,6 +163,24 @@ const book = (overrides = {}) => ({
...overrides,
});
+// Default write-target row matching the single default book most tests
+// discover, so existing single-book scenarios keep resolving the same way
+// selectedCreateBook did before it started reading the stored write-target.
+// Tests exercising multi-book resolution, a missing write-target, an alias,
+// or a denied one override this in their own body.
+function stubWriteTarget(externalUrl = BOOK_URL, aliasUrl = null) {
+ mocks.query.mockImplementation(async sql => {
+ if (sql.includes('is_write_target')) {
+ return {
+ rows: externalUrl
+ ? [{ external_url: externalUrl, discovery_alias_url: aliasUrl }]
+ : [],
+ };
+ }
+ return { rows: [] };
+ });
+}
+
const mappedLocalHash = (contact = mapped()) => localContactHash({
uid: contact.uid,
displayName: contact.display_name,
@@ -278,6 +299,7 @@ beforeEach(() => {
runtime.inTransaction = false;
runtime.events = [];
mocks.randomUUID.mockReturnValue(UID);
+ stubWriteTarget();
});
describe('local-only contact mutations', () => {
@@ -545,6 +567,60 @@ describe('remote-first mapped lifecycle', () => {
expect(mocks.withTransaction).toHaveBeenCalledOnce();
});
+ // A subscribed (or lookup) secondary is read-only from MailFlow regardless
+ // of server write capability — the load-bearing invariant this slice's
+ // write routing must uphold, not just for creates/exports but for edits and
+ // deletes of a contact already mapped into a non-write-target book.
+ it('refuses to update a contact mapped into a book that is not the write-target', async () => {
+ transactions(preflightHandler({
+ contact: mapped({ mapping_is_write_target: false }),
+ }));
+
+ await expect(updateContact(USER_ID, CONTACT_ID, draft())).rejects.toMatchObject({
+ code: 'ERR_CARDDAV_READ_ONLY',
+ });
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ expect(mocks.withTransaction).toHaveBeenCalledOnce();
+ });
+
+ it('refuses to delete a contact mapped into a book that is not the write-target', async () => {
+ transactions(preflightHandler({
+ contact: mapped({ mapping_is_write_target: false }),
+ }));
+
+ await expect(deleteContact(USER_ID, CONTACT_ID)).rejects.toMatchObject({
+ code: 'ERR_CARDDAV_READ_ONLY',
+ });
+ expect(mocks.deleteCardResource).not.toHaveBeenCalled();
+ expect(mocks.withTransaction).toHaveBeenCalledOnce();
+ });
+
+ it('reads a mapped contact without the write-target column on a not-yet-migrated (transitional) schema', async () => {
+ const transitionalPreflight = preflightHandler();
+ let savepointRolledBack = false;
+ transactions(
+ async (sql, params) => {
+ if (sql.includes('FROM contacts c') && sql.includes('mapping_is_write_target')) {
+ throw Object.assign(new Error('column "is_write_target" does not exist'), { code: '42703' });
+ }
+ if (sql === 'ROLLBACK TO SAVEPOINT carddav_read_contact') savepointRolledBack = true;
+ return transitionalPreflight(sql, params);
+ },
+ commitHandler(),
+ );
+ protocolMock(mocks.putCardResource, { href: HREF, etag: '"intermediate"' });
+ protocolMock(mocks.fetchCardResource, () => ({
+ href: HREF,
+ etag: '"remote-2"',
+ vcard: mocks.putCardResource.mock.calls[0][0].vcard,
+ }));
+
+ await expect(updateContact(USER_ID, CONTACT_ID, draft())).resolves.toEqual(confirmedRow());
+
+ expect(savepointRolledBack).toBe(true);
+ expect(mocks.putCardResource).toHaveBeenCalledOnce();
+ });
+
it('rejects a different interactive update while an intent awaits recovery', async () => {
transactions(preflightHandler({ contact: pendingUpdate(CANONICAL_VCARD) }));
@@ -832,16 +908,20 @@ describe('remote creates and export', () => {
expect(mocks.putCardResource).not.toHaveBeenCalled();
});
- it('discovers, selects the first writable book, and uses one UID for the href and vCard', async () => {
- const denied = book({
- url: 'https://dav.example.test/books/denied/',
- capabilities: { create: 'denied', update: 'denied', delete: 'denied' },
+ it('discovers, resolves the stored write-target book by external_url, and uses one UID for the href and vCard', async () => {
+ // The write-target book (matching BOOK_URL via stubWriteTarget()) is discovered
+ // second and would lose to a "first create-capable book" rule if one still
+ // existed; it must still be the one selected, proving resolution is by the
+ // stored external_url, never discovery order.
+ const otherCreateCapable = book({
+ url: 'https://dav.example.test/books/other/',
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
});
const versionFour = book({
addressData: [{ contentType: 'text/vcard', version: '4.0' }],
});
transactions(preflightHandler({ contact: null }), commitHandler());
- mocks.discoverAddressBooks.mockResolvedValue([denied, versionFour]);
+ mocks.discoverAddressBooks.mockResolvedValue([otherCreateCapable, versionFour]);
protocolMock(mocks.putCardResource, { href: HREF, etag: '"created"' });
protocolMock(mocks.fetchCardResource, {
href: HREF,
@@ -859,6 +939,81 @@ describe('remote creates and export', () => {
}));
});
+ it('resolves the write-target book by its discovery alias when the DB holds the reconciled canonical URL', async () => {
+ // carddavSync.js reconciles a discovery alias by rewriting external_url to
+ // the canonical URL it redirects to (advanceDiscoveredBookState), but a
+ // fresh discovery snapshot keeps returning the alias forever afterward.
+ const aliasUrl = 'https://dav.example.test/books/alias/';
+ stubWriteTarget(BOOK_URL, aliasUrl);
+ const aliasedBook = book({ url: aliasUrl });
+ transactions(preflightHandler({ contact: null }), commitHandler());
+ mocks.discoverAddressBooks.mockResolvedValue([aliasedBook]);
+ protocolMock(mocks.putCardResource, { href: HREF, etag: '"created"' });
+ protocolMock(mocks.fetchCardResource, { href: HREF, etag: '"remote-1"', vcard: CANONICAL_VCARD });
+
+ await createContact(USER_ID, draft());
+
+ expect(mocks.putCardResource).toHaveBeenCalledWith(expect.objectContaining({ url: aliasUrl }));
+ });
+
+ it('rejects create with a typed error and no PUT when no write-target book is configured', async () => {
+ stubWriteTarget(null);
+ transactions(preflightHandler({ contact: null }));
+ const otherCreateCapable = book({ url: 'https://dav.example.test/books/other/' });
+ mocks.discoverAddressBooks.mockResolvedValue([otherCreateCapable]);
+
+ await expect(createContact(USER_ID, draft()))
+ .rejects.toMatchObject({ code: 'ERR_CARDDAV_NO_WRITE_TARGET' });
+
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the first capable book on a not-yet-migrated (transitional) schema', async () => {
+ mocks.query.mockImplementation(async sql => {
+ if (sql.includes('is_write_target')) {
+ throw Object.assign(new Error('column "is_write_target" does not exist'), { code: '42703' });
+ }
+ throw new Error('unexpected query on the transitional schema');
+ });
+ transactions(preflightHandler({ contact: null }), commitHandler());
+ const denied = book({
+ url: 'https://dav.example.test/books/denied/',
+ capabilities: { create: 'denied', update: 'denied', delete: 'denied' },
+ });
+ mocks.discoverAddressBooks.mockResolvedValue([denied, book()]);
+ protocolMock(mocks.putCardResource, { href: HREF, etag: '"created"' });
+ protocolMock(mocks.fetchCardResource, { href: HREF, etag: '"remote-1"', vcard: CANONICAL_VCARD });
+
+ await createContact(USER_ID, draft());
+
+ expect(mocks.putCardResource).toHaveBeenCalledWith(expect.objectContaining({ url: BOOK_URL }));
+ });
+
+ it('rejects create with no fallback when the write-target book is absent from the fresh snapshot', async () => {
+ transactions(preflightHandler({ contact: null }));
+ const otherCreateCapable = book({ url: 'https://dav.example.test/books/other/' });
+ mocks.discoverAddressBooks.mockResolvedValue([otherCreateCapable]);
+
+ await expect(createContact(USER_ID, draft()))
+ .rejects.toMatchObject({ code: 'ERR_CARDDAV_NO_WRITE_TARGET' });
+
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ });
+
+ it('rejects create with no fallback when the write-target book is now denied create', async () => {
+ transactions(preflightHandler({ contact: null }));
+ const otherCreateCapable = book({ url: 'https://dav.example.test/books/other/' });
+ const deniedWriteTarget = book({
+ capabilities: { create: 'denied', update: 'allowed', delete: 'allowed' },
+ });
+ mocks.discoverAddressBooks.mockResolvedValue([otherCreateCapable, deniedWriteTarget]);
+
+ await expect(createContact(USER_ID, draft()))
+ .rejects.toMatchObject({ code: 'ERR_CARDDAV_READ_ONLY' });
+
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ });
+
it('checks the deterministic UID href after an ambiguous create before retrying PUT', async () => {
transactions(preflightHandler({ contact: null }), commitHandler());
mocks.discoverAddressBooks.mockResolvedValue([book()]);
@@ -980,6 +1135,33 @@ describe('remote creates and export', () => {
expect(mocks.putCardResource).toHaveBeenCalledOnce();
});
+ it('exports to the write-target book only, never a server-writable secondary in the same snapshot', async () => {
+ transactions(preflightHandler({ contact: mapped({ href: null, source: 'local' }) }), commitHandler());
+ protocolMock(mocks.putCardResource, { href: HREF, etag: '"created"' });
+ protocolMock(mocks.fetchCardResource, {
+ href: HREF,
+ etag: '"remote-1"',
+ vcard: CANONICAL_VCARD,
+ });
+ const writableSecondary = book({ url: 'https://dav.example.test/books/secondary/' });
+
+ await exportExistingContact(USER_ID, CONTACT_ID, { books: [writableSecondary, book()] });
+
+ expect(mocks.putCardResource).toHaveBeenCalledOnce();
+ expect(mocks.putCardResource).toHaveBeenCalledWith(expect.objectContaining({ url: BOOK_URL }));
+ });
+
+ it('rejects export with no fallback when no write-target book is configured', async () => {
+ stubWriteTarget(null);
+ transactions(preflightHandler({ contact: mapped({ href: null, source: 'local' }) }));
+ const otherCreateCapable = book({ url: 'https://dav.example.test/books/other/' });
+
+ await expect(exportExistingContact(USER_ID, CONTACT_ID, { books: [otherCreateCapable] }))
+ .rejects.toMatchObject({ code: 'ERR_CARDDAV_NO_WRITE_TARGET' });
+
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ });
+
it('rejects an export planned by a stale connection generation before remote I/O', async () => {
const replacement = {
...integration,
@@ -1323,6 +1505,28 @@ describe('MailFlow CardDAV-server seams', () => {
expect(mocks.withTransaction).toHaveBeenCalledOnce();
});
+ it('rejects a MailFlow CardDAV-server create with no fallback when no write-target book is configured', async () => {
+ stubWriteTarget(null);
+ transactions(async sql => {
+ if (sql.includes('FROM address_books')) {
+ return { rows: [{ id: LOCAL_BOOK_ID, source: 'local' }] };
+ }
+ if (sql.includes('FROM contacts c')) return { rows: [] };
+ if (sql.includes('FROM user_integrations')) return { rows: [integration] };
+ return { rows: [], rowCount: 1 };
+ });
+ const otherCreateCapable = book({ url: 'https://dav.example.test/books/other/' });
+ mocks.discoverAddressBooks.mockResolvedValue([otherCreateCapable]);
+
+ await expect(createContactFromVCard(USER_ID, {
+ localAddressBookId: LOCAL_BOOK_ID,
+ uid: UID,
+ rawVCard: BASE_VCARD,
+ })).rejects.toMatchObject({ code: 'ERR_CARDDAV_NO_WRITE_TARGET' });
+
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ });
+
it('rejects a stale local ETag before an external request', async () => {
transactions(preflightHandler({ contact: mapped({ etag: 'current-local-etag' }) }));
@@ -1335,6 +1539,33 @@ describe('MailFlow CardDAV-server seams', () => {
expect(mocks.putCardResource).not.toHaveBeenCalled();
});
+ it('refuses to replace a contact mapped into a book that is not the write-target', async () => {
+ transactions(preflightHandler({
+ contact: mapped({ mapping_is_write_target: false }),
+ }));
+
+ await expect(replaceContactFromVCard(USER_ID, {
+ localAddressBookId: BOOK_ID,
+ uid: UID,
+ rawVCard: CANONICAL_VCARD,
+ expectedLocalEtag: 'local-etag-before',
+ })).rejects.toMatchObject({ code: 'ERR_CARDDAV_READ_ONLY' });
+ expect(mocks.putCardResource).not.toHaveBeenCalled();
+ });
+
+ it('refuses to delete-from-vCard a contact mapped into a book that is not the write-target', async () => {
+ transactions(preflightHandler({
+ contact: mapped({ mapping_is_write_target: false }),
+ }));
+
+ await expect(deleteContactFromVCard(USER_ID, {
+ localAddressBookId: BOOK_ID,
+ uid: UID,
+ expectedLocalEtag: 'local-etag-before',
+ })).rejects.toMatchObject({ code: 'ERR_CARDDAV_READ_ONLY' });
+ expect(mocks.deleteCardResource).not.toHaveBeenCalled();
+ });
+
it('resolves delete ownership by local book plus UID and enforces the ETag', async () => {
transactions(preflightHandler(), commitHandler({ row: null }));
protocolMock(mocks.deleteCardResource, { href: HREF, status: 204 });
diff --git a/backend/src/services/carddavLookupService.js b/backend/src/services/carddavLookupService.js
new file mode 100644
index 0000000..dc6b4c6
--- /dev/null
+++ b/backend/src/services/carddavLookupService.js
@@ -0,0 +1,156 @@
+import { query } from './db.js';
+import { parseVCard } from '../utils/vcard.js';
+import { decodeBase64Photo } from '../utils/vcardDocument.js';
+
+// Inbound-sender avatar resolution for lookup-only CardDAV books.
+//
+// A lookup-only book (is_lookup_source && !is_subscribed) retains each remote
+// object as a ledger row (mapping_status='lookup') with no materialized contact
+// and — by design — no photo_data column (see multi-book-design.md, key
+// decision 2). When an inbound sender resolves only against such a book its
+// avatar is produced lazily: parse the retained vCard and pull its PHOTO through
+// the same bounded decode path the rest of CardDAV uses. decodeBase64Photo
+// enforces the 512 KiB limit and rejects malformed data, so an oversized or
+// broken PHOTO yields no avatar rather than an unbounded buffer or a crash.
+//
+// That parse is comparatively expensive and the avatar endpoint is hit once per
+// visible message row, so decoded results are memoized in a small in-process LRU
+// keyed by (userId, lowercased email). The img URL is stable per email, so the
+// browser caches the bytes too (Cache-Control on the route); this cache only
+// spares the server the repeat DB read + vCard parse. It is intentionally
+// best-effort: a sync that rewrites a sender's photo becomes visible once the
+// entry's TTL elapses or it is evicted — acceptable for an avatar, and the
+// escape hatch (a projected photo column) is deliberately deferred.
+
+const PHOTO_CACHE_MAX_ENTRIES = 256;
+const PHOTO_CACHE_TTL_MS = 10 * 60 * 1000;
+
+// Map iteration order is insertion order, so re-inserting on read gives LRU
+// recency and deleting the first key evicts the least-recently-used entry.
+const photoCache = new Map();
+
+function cacheKey(userId, email) {
+ return `${userId} ${email}`;
+}
+
+function cacheGet(key) {
+ const entry = photoCache.get(key);
+ if (!entry) return undefined;
+ if (entry.expiresAt <= Date.now()) {
+ photoCache.delete(key);
+ return undefined;
+ }
+ photoCache.delete(key);
+ photoCache.set(key, entry);
+ return entry.value;
+}
+
+function cacheSet(key, value) {
+ photoCache.delete(key);
+ photoCache.set(key, { value, expiresAt: Date.now() + PHOTO_CACHE_TTL_MS });
+ while (photoCache.size > PHOTO_CACHE_MAX_ENTRIES) {
+ photoCache.delete(photoCache.keys().next().value);
+ }
+}
+
+// Test-only: drop all memoized avatars so LRU/TTL behavior is deterministic.
+export function _clearLookupPhotoCache() {
+ photoCache.clear();
+}
+
+// Extract raw image bytes for a lookup vCard's PHOTO, or null when it has none,
+// is unparseable, or trips the bounded photo decoder (e.g. exceeds 512 KiB).
+function decodeLookupPhoto(vcard) {
+ let photoData;
+ try {
+ photoData = parseVCard(vcard).photoData;
+ } catch {
+ return null;
+ }
+ if (typeof photoData !== 'string' || !photoData.startsWith('data:')) return null;
+ const match = /^data:([^;,]+);base64,(.*)$/is.exec(photoData);
+ if (!match) return null;
+ try {
+ return { mime: match[1], bytes: decodeBase64Photo(match[2]) };
+ } catch {
+ return null;
+ }
+}
+
+// The retained lookup rows for a user's lookup-only carddav books. $1 = userId;
+// callers append the primary_email predicate ($2) and ordering. Shared by the
+// single and batched probes so their scoping (lookup status, ownership, source,
+// lookup-source flag) can never drift apart.
+const LOOKUP_LEDGER_SOURCE = `
+ FROM carddav_remote_objects o
+ JOIN address_books ab ON ab.id = o.address_book_id
+ WHERE o.mapping_status = 'lookup'
+ AND ab.user_id = $1
+ AND ab.source = 'carddav'
+ AND ab.is_lookup_source = true`;
+
+// Resolve an inbound sender's avatar from the user's lookup-only books. Returns
+// { mime, bytes } for the retained vCard's PHOTO, or null when the sender is not
+// in any lookup book (or that vCard carries no usable photo). Callers use this
+// only after a miss in the materialized contacts table, so contacts-table photos
+// always win over the ledger fallback.
+export async function resolveLookupPhoto(userId, email) {
+ const normalized = String(email ?? '').trim().toLowerCase();
+ if (!normalized) return null;
+
+ const key = cacheKey(userId, normalized);
+ const cached = cacheGet(key);
+ if (cached !== undefined) return cached;
+
+ const { rows } = await query(
+ `SELECT o.vcard${LOOKUP_LEDGER_SOURCE}
+ AND o.primary_email = $2
+ ORDER BY o.updated_at DESC
+ LIMIT 1`,
+ [userId, normalized],
+ );
+ const result = rows.length ? decodeLookupPhoto(rows[0].vcard) : null;
+ cacheSet(key, result);
+ return result;
+}
+
+// Batched sibling of resolveLookupPhoto: resolve many senders' avatars in a
+// single DB round-trip. A message page can name hundreds of distinct lookup-only
+// senders; probing one query each (a Promise.all fan-out) floods the ~20-slot
+// connection pool. Cache hits are served from the shared LRU and only the misses
+// reach the DB, in one `primary_email = ANY(...)` probe whose DISTINCT ON keeps
+// the most-recent row per sender — the same choice resolveLookupPhoto's LIMIT 1
+// makes. Per-sender decode + memoization is identical, so both functions share a
+// cache and the photo route keeps reading whatever this primed. Returns a Map of
+// normalized email -> { mime, bytes } | null covering every requested email.
+export async function resolveLookupPhotos(userId, emails) {
+ const results = new Map();
+ const misses = [];
+ for (const email of emails) {
+ const normalized = String(email ?? '').trim().toLowerCase();
+ if (!normalized || results.has(normalized)) continue;
+ const cached = cacheGet(cacheKey(userId, normalized));
+ if (cached !== undefined) {
+ results.set(normalized, cached);
+ continue;
+ }
+ results.set(normalized, null);
+ misses.push(normalized);
+ }
+ if (!misses.length) return results;
+
+ const { rows } = await query(
+ `SELECT DISTINCT ON (o.primary_email) o.primary_email, o.vcard${LOOKUP_LEDGER_SOURCE}
+ AND o.primary_email = ANY($2::text[])
+ ORDER BY o.primary_email, o.updated_at DESC`,
+ [userId, misses],
+ );
+ const vcardByEmail = new Map(rows.map(row => [row.primary_email, row.vcard]));
+ for (const email of misses) {
+ const vcard = vcardByEmail.get(email);
+ const result = vcard ? decodeLookupPhoto(vcard) : null;
+ cacheSet(cacheKey(userId, email), result);
+ results.set(email, result);
+ }
+ return results;
+}
diff --git a/backend/src/services/carddavLookupService.test.js b/backend/src/services/carddavLookupService.test.js
new file mode 100644
index 0000000..0ff468e
--- /dev/null
+++ b/backend/src/services/carddavLookupService.test.js
@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('./db.js', () => ({ query: vi.fn() }));
+
+const { query } = await import('./db.js');
+const { resolveLookupPhoto, resolveLookupPhotos, _clearLookupPhotoCache } = await import('./carddavLookupService.js');
+
+const PHOTO_BYTES = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46]);
+const PHOTO_B64 = PHOTO_BYTES.toString('base64');
+
+function lookupVCard(photo) {
+ return [
+ 'BEGIN:VCARD',
+ 'VERSION:3.0',
+ 'UID:lookup-1',
+ 'FN:Lookup Sender',
+ 'EMAIL:sender@example.test',
+ ...(photo ? [`PHOTO;ENCODING=b;TYPE=JPEG:${photo}`] : []),
+ 'END:VCARD',
+ ].join('\r\n');
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ _clearLookupPhotoCache();
+});
+
+describe('resolveLookupPhoto', () => {
+ it('decodes the retained vCard PHOTO from a lookup-only book by email', async () => {
+ query.mockResolvedValueOnce({ rows: [{ vcard: lookupVCard(PHOTO_B64) }] });
+
+ const photo = await resolveLookupPhoto('user-1', 'Sender@Example.test');
+
+ expect(photo).toEqual({ mime: 'image/jpeg', bytes: PHOTO_BYTES });
+ const [sql, params] = query.mock.calls[0];
+ expect(sql).toContain("o.mapping_status = 'lookup'");
+ expect(sql).toContain('ab.is_lookup_source = true');
+ expect(sql).toContain("ab.source = 'carddav'");
+ // Email is normalized to lower-case before the ledger probe.
+ expect(params).toEqual(['user-1', 'sender@example.test']);
+ });
+
+ it('memoizes the decoded avatar so a repeat request skips the DB and re-parse', async () => {
+ query.mockResolvedValueOnce({ rows: [{ vcard: lookupVCard(PHOTO_B64) }] });
+
+ const first = await resolveLookupPhoto('user-1', 'sender@example.test');
+ const second = await resolveLookupPhoto('user-1', 'sender@example.test');
+
+ expect(second).toEqual(first);
+ expect(query).toHaveBeenCalledTimes(1);
+ });
+
+ it('memoizes a miss so an absent sender is not re-queried on every message row', async () => {
+ query.mockResolvedValueOnce({ rows: [] });
+
+ expect(await resolveLookupPhoto('user-1', 'nobody@example.test')).toBeNull();
+ expect(await resolveLookupPhoto('user-1', 'nobody@example.test')).toBeNull();
+ expect(query).toHaveBeenCalledTimes(1);
+ });
+
+ it('returns null when the lookup vCard carries no PHOTO', async () => {
+ query.mockResolvedValueOnce({ rows: [{ vcard: lookupVCard(null) }] });
+
+ expect(await resolveLookupPhoto('user-1', 'sender@example.test')).toBeNull();
+ });
+
+ it('refuses to serve a PHOTO that exceeds the bounded decode limit', async () => {
+ // 600 KiB of decoded image (819,200 base64 chars) — over decodeBase64Photo's
+ // 512 KiB ceiling but under the 1 MiB vCard limit. It MUST be line-folded:
+ // as one physical line it would trip the parser's 64 KiB physical-line limit
+ // first and the test would pass even with the size bound deleted. Folded into
+ // <64 KiB physical lines, the parser unfolds it cleanly and the 512 KiB PHOTO
+ // bound is the check that rejects it (delete that bound and this goes red).
+ const oversized = 'A'.repeat(819_200);
+ const CHUNK = 8_000;
+ const photoLines = [`PHOTO;ENCODING=b;TYPE=JPEG:${oversized.slice(0, CHUNK)}`];
+ for (let index = CHUNK; index < oversized.length; index += CHUNK) {
+ photoLines.push(` ${oversized.slice(index, index + CHUNK)}`);
+ }
+ const vcard = [
+ 'BEGIN:VCARD',
+ 'VERSION:3.0',
+ 'UID:lookup-1',
+ 'FN:Lookup Sender',
+ 'EMAIL:sender@example.test',
+ ...photoLines,
+ 'END:VCARD',
+ ].join('\r\n');
+ query.mockResolvedValueOnce({ rows: [{ vcard }] });
+
+ expect(await resolveLookupPhoto('user-1', 'sender@example.test')).toBeNull();
+ });
+
+ it('returns null for a blank email without touching the DB', async () => {
+ expect(await resolveLookupPhoto('user-1', ' ')).toBeNull();
+ expect(query).not.toHaveBeenCalled();
+ });
+});
+
+describe('resolveLookupPhotos (batched)', () => {
+ it('resolves N distinct senders in a single DB round-trip', async () => {
+ query.mockResolvedValueOnce({ rows: [
+ { primary_email: 'alice@example.test', vcard: lookupVCard(PHOTO_B64) },
+ { primary_email: 'carol@example.test', vcard: lookupVCard(PHOTO_B64) },
+ ] });
+
+ const photos = await resolveLookupPhotos('user-1', [
+ 'Alice@Example.test', 'bob@example.test', 'carol@example.test',
+ ]);
+
+ // One probe for the whole page — never one per distinct sender.
+ expect(query).toHaveBeenCalledTimes(1);
+ const [sql, params] = query.mock.calls[0];
+ expect(sql).toContain('primary_email = ANY($2::text[])');
+ expect(sql).toContain('DISTINCT ON (o.primary_email)');
+ // Deduped and lower-cased before the probe.
+ expect(params).toEqual([
+ 'user-1',
+ ['alice@example.test', 'bob@example.test', 'carol@example.test'],
+ ]);
+ expect(photos.get('alice@example.test')).toEqual({ mime: 'image/jpeg', bytes: PHOTO_BYTES });
+ expect(photos.get('carol@example.test')).toEqual({ mime: 'image/jpeg', bytes: PHOTO_BYTES });
+ // A candidate with no ledger row resolves to a memoized null, not undefined.
+ expect(photos.get('bob@example.test')).toBeNull();
+ });
+
+ it('serves cache hits without a probe and shares the cache with resolveLookupPhoto', async () => {
+ query.mockResolvedValueOnce({ rows: [
+ { primary_email: 'alice@example.test', vcard: lookupVCard(PHOTO_B64) },
+ ] });
+
+ await resolveLookupPhotos('user-1', ['alice@example.test']);
+ expect(query).toHaveBeenCalledTimes(1);
+
+ // A second batch for the same sender is fully cached — no new probe.
+ const again = await resolveLookupPhotos('user-1', ['Alice@Example.test']);
+ expect(again.get('alice@example.test')).toEqual({ mime: 'image/jpeg', bytes: PHOTO_BYTES });
+ // The single-email route reads the same primed entry the batch wrote.
+ expect(await resolveLookupPhoto('user-1', 'alice@example.test'))
+ .toEqual({ mime: 'image/jpeg', bytes: PHOTO_BYTES });
+ expect(query).toHaveBeenCalledTimes(1);
+ });
+
+ it('issues no query for an empty or blank-only candidate set', async () => {
+ expect(await resolveLookupPhotos('user-1', [])).toEqual(new Map());
+ expect(await resolveLookupPhotos('user-1', ['', ' '])).toEqual(new Map());
+ expect(query).not.toHaveBeenCalled();
+ });
+});
diff --git a/backend/src/services/carddavMappingState.js b/backend/src/services/carddavMappingState.js
index f50e07c..53e4f1e 100644
--- a/backend/src/services/carddavMappingState.js
+++ b/backend/src/services/carddavMappingState.js
@@ -303,6 +303,91 @@ export async function applyRemoteTombstone(client, change) {
return applyRemoteTombstoneState(client, change, true);
}
+// Multi-book lookup projection: retain a remote object for inbound-sender
+// resolution without materializing a local contact. A lookup row keeps the
+// parsed vCard, extracted primary_email, and a projected lookup_display_name
+// but has local_contact_id = NULL and mapping_status = 'lookup', so it can
+// never enter the contacts list, be edited/exported, conflict, or collide with
+// the per-contact active-mapping index (that index excludes NULL contacts).
+// Any pending push intent is cleared: a lookup book is read-only from MailFlow.
+
+// Bind budget: each row contributes LOOKUP_UPSERT_COLUMNS_PER_ROW parameters,
+// and PostgreSQL rejects a single statement carrying more than 65,535 binds. A
+// lookup delta can carry up to DAV_MAX_SYNC_MEMBERS (50,000) members (see
+// carddavClient.js), which at 8 binds/row would need 400,000 binds, so the
+// upsert must be chunked. 4,000 rows is 32,000 binds — comfortably under the
+// limit even if a column is ever added — and keeps each statement small.
+const LOOKUP_UPSERT_COLUMNS_PER_ROW = 8;
+const LOOKUP_UPSERT_CHUNK_ROWS = 4000;
+
+async function upsertLookupObjectChunk(client, chunk) {
+ const tuples = chunk.map((_, index) => {
+ const base = index * LOOKUP_UPSERT_COLUMNS_PER_ROW;
+ return `($${base + 1},$${base + 2},$${base + 3},$${base + 4},$${base + 5},`
+ + `NULL,'lookup',$${base + 6},$${base + 7},NULL,$${base + 8},NOW())`;
+ });
+ const params = chunk.flatMap(change => [
+ change.addressBookId,
+ change.href,
+ change.remoteEtag ?? null,
+ change.vcard,
+ change.primaryEmail ?? null,
+ change.vcardVersion ?? null,
+ change.remoteSemanticHash ?? null,
+ change.lookupDisplayName ?? null,
+ ]);
+ const result = await client.query(
+ `INSERT INTO carddav_remote_objects (
+ address_book_id, href, remote_etag, vcard, primary_email,
+ local_contact_id, mapping_status, vcard_version, remote_semantic_hash,
+ local_contact_hash, lookup_display_name, last_synced_at
+ ) VALUES ${tuples.join(',')}
+ ON CONFLICT (address_book_id, href) DO UPDATE SET
+ remote_etag = EXCLUDED.remote_etag,
+ vcard = EXCLUDED.vcard,
+ primary_email = EXCLUDED.primary_email,
+ local_contact_id = NULL,
+ mapping_status = 'lookup',
+ vcard_version = EXCLUDED.vcard_version,
+ remote_semantic_hash = EXCLUDED.remote_semantic_hash,
+ local_contact_hash = NULL,
+ lookup_display_name = EXCLUDED.lookup_display_name,
+ pending_operation = NULL, pending_vcard = NULL, pending_local_hash = NULL,
+ pending_remote_semantic_hash = NULL, pending_started_at = NULL,
+ mapping_revision = carddav_remote_objects.mapping_revision + 1,
+ last_synced_at = NOW(), last_push_error_code = NULL, last_push_error_at = NULL,
+ updated_at = NOW()`,
+ params,
+ );
+ return result.rowCount;
+}
+
+// Every changed row in a delta is written in multi-row upserts rather than one
+// awaited round trip apiece, chunked to stay under PostgreSQL's per-statement
+// bind limit (see LOOKUP_UPSERT_CHUNK_ROWS). The caller runs this inside its
+// sync transaction, so every chunk shares that transaction and the ledger
+// update stays atomic. Returns the total number of rows written.
+export async function upsertLookupObjects(client, changes) {
+ if (!changes.length) return 0;
+ let written = 0;
+ for (let start = 0; start < changes.length; start += LOOKUP_UPSERT_CHUNK_ROWS) {
+ written += await upsertLookupObjectChunk(
+ client,
+ changes.slice(start, start + LOOKUP_UPSERT_CHUNK_ROWS),
+ );
+ }
+ return written;
+}
+
+export async function removeLookupObjects(client, { addressBookId, hrefs }) {
+ if (!hrefs.length) return { rowCount: 0 };
+ return client.query(
+ `DELETE FROM carddav_remote_objects
+ WHERE address_book_id = $1 AND href = ANY($2::text[])`,
+ [addressBookId, hrefs],
+ );
+}
+
export async function resolveCarddavConflict(client, change) {
requireExpectedRevision(change);
const mapping = change.remoteTombstone
@@ -411,24 +496,192 @@ export async function refreshUnresolvedConflict(client, change) {
return { ok: true, mappingRevision: String(revision), conflict };
}
+function isUndefinedColumn(error) {
+ return error?.code === '42703';
+}
+
+function isNameCollisionViolation(error) {
+ return error.code === '23505' && error.constraint === 'address_books_user_id_name_key';
+}
+
+// Does this schema have the multi-book role columns yet (added by the
+// multi-book migration)? Probed with a SAVEPOINT because this runs inside the
+// caller's sync transaction: an undefined_column error would otherwise abort
+// that whole transaction, not just this one query, on a not-yet-migrated
+// (transitional, mid-deploy) database.
+async function supportsMultiBookRoles(client, userId) {
+ await client.query('SAVEPOINT carddav_multi_book_probe');
+ try {
+ await client.query(
+ `SELECT 1 FROM address_books
+ WHERE user_id = $1 AND source = 'carddav' AND is_write_target = true
+ LIMIT 1`,
+ [userId],
+ );
+ await client.query('RELEASE SAVEPOINT carddav_multi_book_probe');
+ return true;
+ } catch (error) {
+ if (!isUndefinedColumn(error)) throw error;
+ await client.query('ROLLBACK TO SAVEPOINT carddav_multi_book_probe');
+ await client.query('RELEASE SAVEPOINT carddav_multi_book_probe');
+ return false;
+ }
+}
+
+// Atomically claims the write-target (+ subscribed) flags for whichever
+// create-capable carddav book of this user currently ranks best — 'allowed'
+// capability before 'unknown', then earliest created_at/id — mirroring the
+// ranking the 0033 migration backfill applied once for already-connected
+// users.
+//
+// An ignored book (neither subscribed nor a lookup source) is not a candidate at
+// any rank. The claim sets is_subscribed alongside is_write_target, so promoting
+// one would silently re-enable a book the user explicitly turned off and
+// materialize it into the contacts list on the next pull — the very thing the
+// per-book roles exist to prevent. When every create-capable book is ignored the
+// claim takes none and the user is left with no write-target: creates then fail
+// with the typed ERR_CARDDAV_NO_WRITE_TARGET the routes already surface (and the
+// export sweep already skips on), which is the honest outcome once the user has
+// excluded every book that could receive a contact — re-including one through the
+// role controls makes it a candidate again. Deciding *for* them by resurrecting an
+// excluded book would be the one outcome they cannot undo by hand.
+//
+// The `NOT EXISTS` guard makes this a no-op whenever the user already
+// has a write-target, so it is safe to call unconditionally, from two seams:
+// - persistDiscoveredBook below, immediately after inserting a brand-new
+// book — correct for every single-book caller (interactive create/export,
+// which only ever discovers or persists one book per call);
+// - carddavSync.js's syncUser, once after every book in a discovery
+// snapshot has been persisted (see the `deferWriteTargetClaim` book flag
+// below), so a multi-book connect ranks the *whole* snapshot in one shot
+// instead of claiming per book in discovery order — a later 'allowed'
+// book must be able to win over an earlier 'unknown' one that would
+// otherwise keep the flag forever purely by having been discovered first
+// (the bug this replaces) — and once more after a sync's stale-book
+// cleanup (see reconcileStaleCarddavBooks) — a connection replacement
+// (new server or user) can delete the old book that held the flag, which
+// would otherwise leave the replacement connection with none.
+export async function claimBestWriteTargetCandidate(client, userId) {
+ await client.query('SAVEPOINT carddav_write_target_claim');
+ try {
+ await client.query(
+ `UPDATE address_books SET
+ is_write_target = true, is_subscribed = true, updated_at = NOW()
+ WHERE id = (
+ SELECT id FROM address_books
+ WHERE user_id = $1 AND source = 'carddav' AND remote_create_capability <> 'denied'
+ AND (is_subscribed OR is_lookup_source)
+ ORDER BY (remote_create_capability = 'allowed') DESC, created_at, id
+ LIMIT 1
+ )
+ AND NOT EXISTS (
+ SELECT 1 FROM address_books
+ WHERE user_id = $1 AND source = 'carddav' AND is_write_target = true
+ )`,
+ [userId],
+ );
+ await client.query('RELEASE SAVEPOINT carddav_write_target_claim');
+ } catch (error) {
+ if (!isUndefinedColumn(error) && error.code !== '23505') throw error;
+ await client.query('ROLLBACK TO SAVEPOINT carddav_write_target_claim');
+ await client.query('RELEASE SAVEPOINT carddav_write_target_claim');
+ }
+}
+
+// Resolve a fresh discovery snapshot's book to an already-persisted row, by
+// its canonical external_url or its recorded discovery alias. Some CardDAV
+// servers keep advertising a stable "alias" href in PROPFIND discovery for a
+// collection whose canonical external_url advanceDiscoveredBookState already
+// rewrote after a REPORT/PUT/DELETE redirect reconciliation; selectedCreateBook
+// (carddavContactService.js) deliberately matches such a book by either URL so
+// write routing keeps working, but an INSERT can only ON CONFLICT on one
+// column. Without this lookup, persisting a book resolved via its alias would
+// insert a second, non-write-target row for the same remote collection
+// instead of updating the existing one — silently orphaning every future
+// mutation mapped through it as read-only.
+async function findDiscoveredBookByUrl(client, userId, url) {
+ const { rows: [existing] } = await client.query(
+ `SELECT id FROM address_books
+ WHERE user_id = $1 AND source = 'carddav'
+ AND (external_url = $2 OR discovery_alias_url = $2)
+ FOR UPDATE`,
+ [userId, url],
+ );
+ return existing || null;
+}
+
export async function persistDiscoveredBook(client, book) {
const capabilities = normalizeCarddavCapabilities(book.capabilities);
const displayName = book.displayName || 'CardDAV';
+ const multiBook = await supportsMultiBookRoles(client, book.userId);
+
+ // Already-persisted book (matched by canonical URL or discovery alias) —
+ // update its capabilities in place. Role flags (is_write_target,
+ // is_subscribed) are never touched here: those are only ever decided once,
+ // at first creation below, or by deliberate role-management elsewhere.
+ const existingBook = multiBook
+ ? await findDiscoveredBookByUrl(client, book.userId, book.url)
+ : null;
+ if (existingBook) {
+ const { rows: [stored] } = await client.query(
+ book.preserveCapabilities === true
+ ? `UPDATE address_books SET updated_at = NOW()
+ WHERE id = $1
+ RETURNING id, external_url, remote_sync_token,
+ remote_sync_revision::text, sync_token,
+ remote_projection_fingerprint`
+ : `UPDATE address_books SET
+ remote_create_capability = $2,
+ remote_update_capability = $3,
+ remote_delete_capability = $4,
+ updated_at = NOW()
+ WHERE id = $1
+ RETURNING id, external_url, remote_sync_token,
+ remote_sync_revision::text, sync_token,
+ remote_projection_fingerprint`,
+ book.preserveCapabilities === true
+ ? [existingBook.id]
+ : [existingBook.id, capabilities.create, capabilities.update, capabilities.delete],
+ );
+ return stored;
+ }
+
const capabilityUpdate = book.preserveCapabilities === true
? ''
: `,
remote_create_capability = EXCLUDED.remote_create_capability,
remote_update_capability = EXCLUDED.remote_update_capability,
remote_delete_capability = EXCLUDED.remote_delete_capability`;
- for (let attempt = 0; attempt < 20; attempt++) {
- const name = attempt === 0 ? displayName : `${displayName} (${attempt + 1})`;
+ // A brand-new carddav book is normally inserted lookup-only (is_write_target,
+ // is_subscribed both false, matching the column defaults exactly): a book
+ // never claims the write-target directly, in per-book discovery order, here —
+ // claimBestWriteTargetCandidate re-ranks the *whole* snapshot of the user's
+ // carddav books by capability priority once the row exists, and assigns the
+ // single is_write_target flag. The one exception is subscribeOnCreate: the
+ // sync loop resolves the book that will become the write-target from the
+ // discovery snapshot (see carddavSync.js) and asks for it to be inserted
+ // *subscribed* so it materializes in that very first sync, and durably —
+ // even if a later sibling book in the same batch fails before the batch-wide
+ // claim runs, or a stale write-target from a replaced connection still holds
+ // the flag this pass. is_write_target stays false here (only the claim sets
+ // it, avoiding the one-write-target unique index while a stale one lingers);
+ // subscribing without the write-target flag is a valid subscribed-secondary
+ // state and satisfies the address_books_write_target_subscribed check.
+ const subscribeOnCreate = multiBook && book.subscribeOnCreate === true;
+ const roleColumns = multiBook ? ', is_write_target, is_subscribed' : '';
+ const roleValues = multiBook ? `,false,${subscribeOnCreate}` : '';
+ let stored;
+ let nameAttempt = 0;
+ let unexpectedRetries = 0;
+ for (;;) {
+ const name = nameAttempt === 0 ? displayName : `${displayName} (${nameAttempt + 1})`;
await client.query('SAVEPOINT carddav_book_name');
try {
- const { rows: [stored] } = await client.query(
+ ({ rows: [stored] } = await client.query(
`INSERT INTO address_books (
user_id, name, source, external_url,
- remote_create_capability, remote_update_capability, remote_delete_capability
- ) VALUES ($1,$2,'carddav',$3,$4,$5,$6)
+ remote_create_capability, remote_update_capability, remote_delete_capability${roleColumns}
+ ) VALUES ($1,$2,'carddav',$3,$4,$5,$6${roleValues})
ON CONFLICT (user_id, external_url)
WHERE source = 'carddav' AND external_url IS NOT NULL
DO UPDATE SET
@@ -445,16 +698,38 @@ export async function persistDiscoveredBook(client, book) {
capabilities.update,
capabilities.delete,
],
- );
+ ));
await client.query('RELEASE SAVEPOINT carddav_book_name');
- return stored;
+ break;
} catch (error) {
if (error.code !== '23505') throw error;
await client.query('ROLLBACK TO SAVEPOINT carddav_book_name');
await client.query('RELEASE SAVEPOINT carddav_book_name');
+ // Only a display-name collision (this user already has a same-named
+ // book) should provoke a rename. Anything else — e.g. a concurrent
+ // insert for this same external_url racing this one — retries the
+ // *identical* name a bounded number of times instead of spuriously
+ // renaming this book for an unrelated conflict.
+ if (isNameCollisionViolation(error)) {
+ nameAttempt += 1;
+ if (nameAttempt >= 20) {
+ throw new Error(`Could not create a local address book for "${displayName}"`, { cause: error });
+ }
+ } else {
+ unexpectedRetries += 1;
+ if (unexpectedRetries >= 5) throw error;
+ }
}
}
- throw new Error(`Could not create a local address book for "${displayName}"`);
+ // The sync loop (createCarddavBook in carddavSync.js) persists every book
+ // of a discovery snapshot individually but defers claiming until the whole
+ // snapshot exists, so it can rank all of them at once (see
+ // claimBestWriteTargetCandidate above); every other caller persists a
+ // single book and wants the claim attempted right away.
+ if (multiBook && book.deferWriteTargetClaim !== true) {
+ await claimBestWriteTargetCandidate(client, book.userId);
+ }
+ return stored;
}
const CAPABILITY_COLUMNS = {
@@ -480,11 +755,35 @@ export async function persistDeniedBookCapability(client, {
);
}
-export async function advanceDiscoveredBookState(client, state) {
- const capabilities = normalizeCarddavCapabilities(state.capabilities);
- return client.query(`
+const ADVANCE_BOOK_STATE_SQL = `
+ UPDATE address_books SET
+ external_url = COALESCE($6, external_url),
+ remote_sync_token = $2,
+ remote_sync_capability = $3,
+ remote_sync_revision = remote_sync_revision + 1,
+ remote_projection_fingerprint = $4,
+ remote_create_capability = $7,
+ remote_update_capability = $8,
+ remote_delete_capability = $9,
+ updated_at = NOW()
+ WHERE id = $1 AND remote_sync_revision = $5::bigint
+ `;
+
+// Same statement, but also records the discovery URL a book's canonical
+// external_url gets rewritten from. A CardDAV discovery PROPFIND can keep
+// advertising a stable "alias" href for a collection that 3xx-redirects
+// (REPORT/PUT/DELETE) to a different canonical URL; when that happens
+// canonicalUrl differs from the row's current external_url (the alias),
+// and the alias is worth keeping so write-target resolution can still match
+// a book by whichever URL a fresh discovery snapshot returns (see
+// writeTargetBookUrls / selectedCreateBook in carddavContactService.js).
+const ADVANCE_BOOK_STATE_WITH_ALIAS_SQL = `
UPDATE address_books SET
external_url = COALESCE($6, external_url),
+ discovery_alias_url = CASE
+ WHEN $6 IS NOT NULL AND $6 <> external_url THEN external_url
+ ELSE discovery_alias_url
+ END,
remote_sync_token = $2,
remote_sync_capability = $3,
remote_sync_revision = remote_sync_revision + 1,
@@ -494,7 +793,11 @@ export async function advanceDiscoveredBookState(client, state) {
remote_delete_capability = $9,
updated_at = NOW()
WHERE id = $1 AND remote_sync_revision = $5::bigint
- `, [
+ `;
+
+export async function advanceDiscoveredBookState(client, state) {
+ const capabilities = normalizeCarddavCapabilities(state.capabilities);
+ const params = [
state.addressBookId,
state.remoteSyncToken,
state.remoteSyncCapability,
@@ -504,5 +807,21 @@ export async function advanceDiscoveredBookState(client, state) {
capabilities.create,
capabilities.update,
capabilities.delete,
- ]);
+ ];
+ // Guarded with a SAVEPOINT + undefined_column fallback (rather than an
+ // information_schema pre-check) because this runs inside the caller's sync
+ // transaction, once per book on every sync — an undefined_column error on
+ // a not-yet-migrated (transitional) schema would otherwise abort that whole
+ // transaction, not just this query.
+ await client.query('SAVEPOINT carddav_book_alias_column');
+ try {
+ const result = await client.query(ADVANCE_BOOK_STATE_WITH_ALIAS_SQL, params);
+ await client.query('RELEASE SAVEPOINT carddav_book_alias_column');
+ return result;
+ } catch (error) {
+ if (!isUndefinedColumn(error)) throw error;
+ await client.query('ROLLBACK TO SAVEPOINT carddav_book_alias_column');
+ await client.query('RELEASE SAVEPOINT carddav_book_alias_column');
+ return client.query(ADVANCE_BOOK_STATE_SQL, params);
+ }
}
diff --git a/backend/src/services/carddavMappingState.test.js b/backend/src/services/carddavMappingState.test.js
index 7c67246..7f3b612 100644
--- a/backend/src/services/carddavMappingState.test.js
+++ b/backend/src/services/carddavMappingState.test.js
@@ -4,6 +4,7 @@ import {
advanceDiscoveredBookState,
applyConfirmedRemoteContact,
applyRemoteTombstone,
+ claimBestWriteTargetCandidate,
lockCarddavMapping,
persistDiscoveredBook,
persistPendingMutationIntent,
@@ -468,23 +469,310 @@ describe('refreshUnresolvedConflict', () => {
});
describe('persistDiscoveredBook', () => {
- it('persists capabilities without overwriting sync state', async () => {
+ it('persists capabilities on an already-discovered book without touching its role flags or sync state', async () => {
+ // Matched by URL (findDiscoveredBookByUrl) — never a fresh INSERT, and
+ // never touches is_write_target/is_subscribed/external_url: those are
+ // only ever decided once, at first creation.
const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/default/' };
- const client = { query: vi.fn(async () => ({ rows: [stored], rowCount: 1 })) };
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) return { rows: [] };
+ if (/SELECT id FROM address_books/.test(sql)) return { rows: [{ id: BOOK_ID }] };
+ return { rows: [stored], rowCount: 1 };
+ }),
+ };
+
await expect(persistDiscoveredBook(client, {
userId: USER_ID,
url: stored.external_url,
displayName: 'Remote',
capabilities: { create: 'allowed', update: 'denied', delete: 'unknown' },
})).resolves.toEqual(stored);
+
+ expect(client.query).not.toHaveBeenCalledWith(
+ expect.stringMatching(/INSERT INTO address_books/),
+ expect.anything(),
+ );
+ const updateCall = client.query.mock.calls.find(([sql]) => /^UPDATE address_books SET/.test(sql));
+ expect(updateCall[0]).toMatch(
+ /remote_create_capability = \$2[\s\S]+remote_update_capability = \$3[\s\S]+remote_delete_capability = \$4[\s\S]+WHERE id = \$1/,
+ );
+ expect(updateCall[0]).not.toMatch(/is_write_target|is_subscribed|external_url\s*=/);
+ expect(updateCall[1]).toEqual([BOOK_ID, 'allowed', 'denied', 'unknown']);
+ });
+
+ it('resolves an existing book by its discovery alias and updates it instead of inserting a duplicate', async () => {
+ // Some CardDAV servers keep advertising a stable "alias" href for a
+ // collection whose canonical external_url advanceDiscoveredBookState
+ // already rewrote (see carddavContactService.js's selectedCreateBook).
+ // Matching only on external_url here would insert a second, non-write-
+ // target row for the same remote collection.
+ const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/canonical/' };
+ const aliasUrl = 'https://dav.example.test/addressbooks/alias/';
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) return { rows: [] };
+ if (/SELECT id FROM address_books/.test(sql)) return { rows: [{ id: BOOK_ID }] };
+ return { rows: [stored], rowCount: 1 };
+ }),
+ };
+
+ await expect(persistDiscoveredBook(client, {
+ userId: USER_ID,
+ url: aliasUrl,
+ displayName: 'Remote',
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ })).resolves.toEqual(stored);
+
+ expect(client.query).toHaveBeenCalledWith(
+ expect.stringMatching(/SELECT id FROM address_books[\s\S]+external_url = \$2 OR discovery_alias_url = \$2/),
+ [USER_ID, aliasUrl],
+ );
+ expect(client.query).not.toHaveBeenCalledWith(
+ expect.stringMatching(/INSERT INTO address_books/),
+ expect.anything(),
+ );
+ const updateCall = client.query.mock.calls.find(([sql]) => /^UPDATE address_books SET/.test(sql));
+ expect(updateCall[1]).toEqual([BOOK_ID, 'allowed', 'allowed', 'allowed']);
+ });
+
+ it('claims the write-target for the first create-capable book a user discovers', async () => {
+ const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/default/' };
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) return { rows: [] };
+ if (/SELECT id FROM address_books/.test(sql)) return { rows: [] };
+ if (/INSERT INTO address_books/.test(sql)) return { rows: [stored], rowCount: 1 };
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await persistDiscoveredBook(client, {
+ userId: USER_ID,
+ url: stored.external_url,
+ displayName: 'Remote',
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ });
+
+ // Every brand-new book is inserted lookup-only (never claims directly,
+ // in per-book discovery order) ...
+ expect(client.query).toHaveBeenCalledWith(
+ expect.stringMatching(
+ /INSERT INTO address_books[\s\S]+is_write_target, is_subscribed[\s\S]+VALUES \(\$1,\$2,'carddav',\$3,\$4,\$5,\$6,false,false\)/,
+ ),
+ [USER_ID, 'Remote', stored.external_url, 'allowed', 'allowed', 'allowed'],
+ );
+ // ... and claimBestWriteTargetCandidate promotes it afterward, since it's
+ // the only (and therefore best) candidate.
+ expect(client.query).toHaveBeenCalledWith(
+ expect.stringMatching(/is_write_target = true, is_subscribed = true[\s\S]+NOT EXISTS/),
+ [USER_ID],
+ );
+ });
+
+ it('never lets a book claim its own write-target directly, in discovery order', async () => {
+ const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/default/' };
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) return { rows: [] };
+ if (/SELECT id FROM address_books/.test(sql)) return { rows: [] };
+ if (/INSERT INTO address_books/.test(sql)) return { rows: [stored], rowCount: 1 };
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await persistDiscoveredBook(client, {
+ userId: USER_ID,
+ url: stored.external_url,
+ displayName: 'Remote',
+ capabilities: { create: 'denied', update: 'denied', delete: 'denied' },
+ });
+
+ expect(client.query).toHaveBeenCalledWith(
+ expect.stringMatching(
+ /INSERT INTO address_books[\s\S]+VALUES \(\$1,\$2,'carddav',\$3,\$4,\$5,\$6,false,false\)/,
+ ),
+ [USER_ID, 'Remote', stored.external_url, 'denied', 'denied', 'denied'],
+ );
+ // The claim attempt still runs (it ranks across this user's *whole*
+ // snapshot of carddav books, not just this one), but its own ranking
+ // excludes denied books, so a lone denied book is never promoted.
+ expect(client.query).toHaveBeenCalledWith(
+ expect.stringMatching(/remote_create_capability <> 'denied'/),
+ [USER_ID],
+ );
+ });
+
+ it('defers the write-target claim when the caller is batching a discovery snapshot', async () => {
+ const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/default/' };
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) return { rows: [] };
+ if (/SELECT id FROM address_books/.test(sql)) return { rows: [] };
+ if (/INSERT INTO address_books/.test(sql)) return { rows: [stored], rowCount: 1 };
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await persistDiscoveredBook(client, {
+ userId: USER_ID,
+ url: stored.external_url,
+ displayName: 'Remote',
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ deferWriteTargetClaim: true,
+ });
+
+ expect(client.query).not.toHaveBeenCalledWith(
+ expect.stringMatching(/is_write_target = true, is_subscribed = true/),
+ expect.anything(),
+ );
+ });
+
+ it('retries an unrelated 23505 with the identical name instead of spuriously renaming the book', async () => {
+ const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/default/' };
+ let insertAttempts = 0;
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) return { rows: [] };
+ if (/SELECT id FROM address_books/.test(sql)) return { rows: [] };
+ if (/INSERT INTO address_books/.test(sql)) {
+ insertAttempts += 1;
+ if (insertAttempts === 1) {
+ // Not a (user_id, name) collision — e.g. a concurrent insert for
+ // this same external_url racing this one.
+ throw Object.assign(new Error('duplicate key'), {
+ code: '23505',
+ constraint: 'some_unrelated_constraint',
+ });
+ }
+ return { rows: [stored], rowCount: 1 };
+ }
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await expect(persistDiscoveredBook(client, {
+ userId: USER_ID,
+ url: stored.external_url,
+ displayName: 'Remote',
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ })).resolves.toEqual(stored);
+
+ const insertCalls = client.query.mock.calls.filter(([sql]) => /INSERT INTO address_books/.test(sql));
+ expect(insertCalls).toHaveLength(2);
+ expect(insertCalls[0][1][1]).toBe('Remote');
+ expect(insertCalls[1][1][1]).toBe('Remote');
+ });
+
+ it('renames only on a genuine display-name collision, retrying with a numbered suffix', async () => {
+ const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/default/' };
+ let insertAttempts = 0;
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) return { rows: [] };
+ if (/SELECT id FROM address_books/.test(sql)) return { rows: [] };
+ if (/INSERT INTO address_books/.test(sql)) {
+ insertAttempts += 1;
+ if (insertAttempts === 1) {
+ throw Object.assign(new Error('duplicate key'), {
+ code: '23505',
+ constraint: 'address_books_user_id_name_key',
+ });
+ }
+ return { rows: [stored], rowCount: 1 };
+ }
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await expect(persistDiscoveredBook(client, {
+ userId: USER_ID,
+ url: stored.external_url,
+ displayName: 'Remote',
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ })).resolves.toEqual(stored);
+
+ const insertCalls = client.query.mock.calls.filter(([sql]) => /INSERT INTO address_books/.test(sql));
+ expect(insertCalls).toHaveLength(2);
+ expect(insertCalls[0][1][1]).toBe('Remote');
+ expect(insertCalls[1][1][1]).toBe('Remote (2)');
+ });
+
+ it('inserts without multi-book role columns on a not-yet-migrated (transitional) schema', async () => {
+ const stored = { id: BOOK_ID, external_url: 'https://dav.example.test/addressbooks/default/' };
+ const client = {
+ query: vi.fn(async sql => {
+ if (/SELECT 1 FROM address_books/.test(sql)) {
+ throw Object.assign(new Error('column "is_write_target" does not exist'), { code: '42703' });
+ }
+ return { rows: [stored], rowCount: 1 };
+ }),
+ };
+
+ await expect(persistDiscoveredBook(client, {
+ userId: USER_ID,
+ url: stored.external_url,
+ displayName: 'Remote',
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ })).resolves.toEqual(stored);
+
+ const insertCall = client.query.mock.calls.find(([sql]) => sql.includes('INSERT INTO address_books'));
+ expect(insertCall[0]).not.toMatch(/is_write_target/);
+ expect(insertCall[1]).toEqual([USER_ID, 'Remote', stored.external_url, 'allowed', 'allowed', 'allowed']);
+ expect(client.query.mock.calls.some(([sql]) => sql === 'ROLLBACK TO SAVEPOINT carddav_multi_book_probe')).toBe(true);
+ // No alias lookup on a not-yet-migrated schema (no discovery_alias_url column).
+ expect(client.query).not.toHaveBeenCalledWith(
+ expect.stringMatching(/SELECT id FROM address_books/),
+ expect.anything(),
+ );
+ });
+
+ it('ranks candidates by capability priority before created_at/id and no-ops once a write-target exists', async () => {
+ const client = { query: vi.fn(async () => ({ rows: [], rowCount: 1 })) };
+
+ await claimBestWriteTargetCandidate(client, USER_ID);
+
expect(client.query).toHaveBeenCalledWith(
expect.stringMatching(
- /INSERT INTO address_books[\s\S]+remote_create_capability[\s\S]+ON CONFLICT[\s\S]+remote_create_capability = EXCLUDED.remote_create_capability/,
+ /UPDATE address_books SET[\s\S]+is_write_target = true, is_subscribed = true[\s\S]+remote_create_capability <> 'denied'[\s\S]+ORDER BY \(remote_create_capability = 'allowed'\) DESC, created_at, id[\s\S]+NOT EXISTS[\s\S]+is_write_target = true/,
),
- [USER_ID, 'Remote', stored.external_url, 'allowed', 'denied', 'unknown'],
+ [USER_ID],
);
});
+ it('swallows a lost write-target race instead of throwing', async () => {
+ const client = {
+ query: vi.fn(async sql => {
+ if (/^UPDATE address_books SET/.test(sql)) {
+ throw Object.assign(new Error('duplicate key'), {
+ code: '23505',
+ constraint: 'carddav_one_write_target_idx',
+ });
+ }
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await expect(claimBestWriteTargetCandidate(client, USER_ID)).resolves.toBeUndefined();
+
+ expect(client.query).toHaveBeenCalledWith('ROLLBACK TO SAVEPOINT carddav_write_target_claim');
+ });
+
+ it('no-ops on a not-yet-migrated (transitional) schema', async () => {
+ const client = {
+ query: vi.fn(async sql => {
+ if (/^UPDATE address_books SET/.test(sql)) {
+ throw Object.assign(new Error('column "is_write_target" does not exist'), { code: '42703' });
+ }
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await expect(claimBestWriteTargetCandidate(client, USER_ID)).resolves.toBeUndefined();
+
+ expect(client.query).toHaveBeenCalledWith('ROLLBACK TO SAVEPOINT carddav_write_target_claim');
+ });
+
it('owns a single denied capability update without changing its siblings', async () => {
const client = { query: vi.fn(async () => ({ rows: [{ id: BOOK_ID }], rowCount: 1 })) };
@@ -533,6 +821,149 @@ describe('persistDiscoveredBook', () => {
],
);
});
+
+ it('records the discovery alias a canonical URL rewrite replaces', async () => {
+ const client = { query: vi.fn(async () => ({ rows: [], rowCount: 1 })) };
+
+ await advanceDiscoveredBookState(client, {
+ addressBookId: BOOK_ID,
+ expectedRemoteRevision: '4',
+ canonicalUrl: 'https://dav.example.test/addressbooks/canonical/',
+ remoteSyncToken: 'opaque-token-2',
+ remoteSyncCapability: 'supported',
+ remoteProjectionFingerprint: 'projection-fingerprint',
+ capabilities: { create: 'allowed', update: 'unknown', delete: 'denied' },
+ });
+
+ expect(client.query).toHaveBeenCalledWith(
+ expect.stringMatching(/discovery_alias_url = CASE[\s\S]+WHEN \$6 IS NOT NULL AND \$6 <> external_url THEN external_url/),
+ [
+ BOOK_ID,
+ 'opaque-token-2',
+ 'supported',
+ 'projection-fingerprint',
+ '4',
+ 'https://dav.example.test/addressbooks/canonical/',
+ 'allowed',
+ 'unknown',
+ 'denied',
+ ],
+ );
+ });
+
+ it('advances book state without the alias column on a not-yet-migrated (transitional) schema', async () => {
+ let attempt = 0;
+ const client = {
+ query: vi.fn(async sql => {
+ if (sql.includes('UPDATE address_books') && sql.includes('discovery_alias_url')) {
+ attempt++;
+ throw Object.assign(new Error('column "discovery_alias_url" does not exist'), { code: '42703' });
+ }
+ return { rows: [], rowCount: 1 };
+ }),
+ };
+
+ await advanceDiscoveredBookState(client, {
+ addressBookId: BOOK_ID,
+ expectedRemoteRevision: '4',
+ canonicalUrl: 'https://dav.example.test/addressbooks/default/',
+ remoteSyncToken: 'opaque-token-2',
+ remoteSyncCapability: 'supported',
+ remoteProjectionFingerprint: 'projection-fingerprint',
+ capabilities: { create: 'allowed', update: 'unknown', delete: 'denied' },
+ });
+
+ expect(attempt).toBe(1);
+ const fallbackCall = client.query.mock.calls.find(([sql]) => (
+ sql.includes('UPDATE address_books') && !sql.includes('discovery_alias_url')
+ ));
+ expect(fallbackCall).toBeDefined();
+ expect(client.query.mock.calls.some(([sql]) => sql === 'ROLLBACK TO SAVEPOINT carddav_book_alias_column')).toBe(true);
+ });
+});
+
+describe('upsertLookupObjects chunking', () => {
+ // Must mirror the constants in carddavMappingState.js: 8 binds per row, and a
+ // chunk small enough that even the largest permitted lookup delta stays under
+ // PostgreSQL's 65,535-bind ceiling.
+ const COLUMNS_PER_ROW = 8;
+ const CHUNK_ROWS = 4000;
+ const PG_BIND_LIMIT = 65535;
+
+ function lookupChange(index) {
+ return {
+ addressBookId: BOOK_ID,
+ href: `https://dav.example.test/addressbooks/lookup/${index}.vcf`,
+ remoteEtag: `"etag-${index}"`,
+ vcard: `BEGIN:VCARD\r\nVERSION:3.0\r\nUID:lookup-${index}\r\nEND:VCARD\r\n`,
+ primaryEmail: `lookup-${index}@example.test`,
+ vcardVersion: '3.0',
+ remoteSemanticHash: `hash-${index}`,
+ lookupDisplayName: `Lookup ${index}`,
+ };
+ }
+
+ function recordingClient() {
+ const inserts = [];
+ const control = [];
+ const client = {
+ query: vi.fn(async (sql, params) => {
+ if (/INSERT INTO carddav_remote_objects/.test(sql)) {
+ inserts.push({ sql, params });
+ return { rowCount: params.length / COLUMNS_PER_ROW };
+ }
+ control.push(sql);
+ return { rows: [], rowCount: 0 };
+ }),
+ };
+ return { client, inserts, control };
+ }
+
+ // Each VALUES tuple ends with ",NOW())"; the ON CONFLICT clause never does, so
+ // this counts exactly the rows a single statement carries — independent of the
+ // parameter array.
+ function rowsInStatement(insert) {
+ return (insert.sql.match(/,NOW\(\)\)/g) || []).length;
+ }
+
+ it('writes nothing and issues no statement for an empty delta', async () => {
+ const { client, inserts } = recordingClient();
+ expect(await mappingState.upsertLookupObjects(client, [])).toBe(0);
+ expect(inserts).toHaveLength(0);
+ });
+
+ it('writes a single-row delta in one statement inside the caller transaction', async () => {
+ const { client, inserts, control } = recordingClient();
+ const written = await mappingState.upsertLookupObjects(client, [lookupChange(0)]);
+ expect(written).toBe(1);
+ expect(inserts).toHaveLength(1);
+ expect(rowsInStatement(inserts[0])).toBe(1);
+ expect(inserts[0].params).toHaveLength(COLUMNS_PER_ROW);
+ // No BEGIN/COMMIT/SAVEPOINT — the chunks share the caller's transaction.
+ expect(control).toEqual([]);
+ });
+
+ it('writes an exactly-full chunk in one statement', async () => {
+ const changes = Array.from({ length: CHUNK_ROWS }, (_, index) => lookupChange(index));
+ const { client, inserts } = recordingClient();
+ const written = await mappingState.upsertLookupObjects(client, changes);
+ expect(written).toBe(CHUNK_ROWS);
+ expect(inserts).toHaveLength(1);
+ expect(rowsInStatement(inserts[0])).toBe(CHUNK_ROWS);
+ expect(inserts[0].params).toHaveLength(CHUNK_ROWS * COLUMNS_PER_ROW);
+ expect(inserts[0].params.length).toBeLessThanOrEqual(PG_BIND_LIMIT);
+ });
+
+ it('splits one row past a full chunk into two statements, each within the bind budget', async () => {
+ const changes = Array.from({ length: CHUNK_ROWS + 1 }, (_, index) => lookupChange(index));
+ const { client, inserts } = recordingClient();
+ const written = await mappingState.upsertLookupObjects(client, changes);
+ expect(written).toBe(CHUNK_ROWS + 1);
+ expect(inserts.map(rowsInStatement)).toEqual([CHUNK_ROWS, 1]);
+ expect(inserts.every(insert => insert.params.length <= PG_BIND_LIMIT)).toBe(true);
+ // Every chunk rebuilds fresh $1-based placeholders.
+ expect(inserts[1].sql).toMatch(/VALUES \(\$1,/);
+ });
});
describe('assertConflictSnapshotsWithinLimit', () => {
diff --git a/backend/src/services/carddavMigration.db.test.js b/backend/src/services/carddavMigration.db.test.js
index a25b6bb..df58a78 100644
--- a/backend/src/services/carddavMigration.db.test.js
+++ b/backend/src/services/carddavMigration.db.test.js
@@ -27,6 +27,8 @@ const databaseNames = {
populatedCollision: `carddav_populated_collision_${databaseSuffix}`,
populatedFirst: `carddav_populated_first_${databaseSuffix}`,
emptyDuplicates: `carddav_empty_duplicates_${databaseSuffix}`,
+ multiBookBackfill: `carddav_multi_book_backfill_${databaseSuffix}`,
+ publishIntentBackfill: `carddav_publish_intent_backfill_${databaseSuffix}`,
};
const UUID_PATTERN =
/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -565,6 +567,45 @@ async function expectConflictRetentionSchema(client) {
]);
}
+async function expectMultiBookSchema(client) {
+ const addressBookColumns = await readColumns(client, 'address_books');
+ expect(addressBookColumns).toMatchObject({
+ is_write_target: { data_type: 'boolean', is_nullable: 'NO', column_default: 'false' },
+ is_subscribed: { data_type: 'boolean', is_nullable: 'NO', column_default: 'false' },
+ is_lookup_source: { data_type: 'boolean', is_nullable: 'NO', column_default: 'true' },
+ });
+
+ const mappingColumns = await readColumns(client, 'carddav_remote_objects');
+ expect(mappingColumns.lookup_display_name).toEqual({
+ data_type: 'text',
+ is_nullable: 'YES',
+ column_default: null,
+ });
+
+ const checks = await readChecks(client, ['address_books', 'carddav_remote_objects']);
+ expect(checks).toEqual(expect.arrayContaining([
+ {
+ table_name: 'address_books',
+ check_clause: '(((NOT is_write_target) OR is_subscribed))',
+ },
+ {
+ table_name: 'carddav_remote_objects',
+ check_clause: "((mapping_status = ANY (ARRAY['pending_materialization'::text, 'synced'::text, 'pending_push'::text, 'conflict'::text, 'lookup'::text])))",
+ },
+ ]));
+
+ const indexDefinitions = await readIndexDefinitions(client, [
+ 'carddav_one_write_target_idx',
+ 'carddav_lookup_email_idx',
+ ]);
+ expect(indexDefinitions.carddav_one_write_target_idx).toBe(
+ "UNIQUE (user_id) WHERE ((source = 'carddav'::text) AND is_write_target)",
+ );
+ expect(indexDefinitions.carddav_lookup_email_idx).toBe(
+ "(primary_email) WHERE (mapping_status = 'lookup'::text)",
+ );
+}
+
it('keeps migration versions unique and orders the CardDAV lifecycle migrations', async () => {
const filenames = (await readdir(migrationsDirectory))
.filter(filename => /^\d{4}_.+\.sql$/.test(filename))
@@ -576,6 +617,9 @@ it('keeps migration versions unique and orders the CardDAV lifecycle migrations'
const expandIndex = filenames.indexOf('0035_carddav_bidirectional_sync.sql');
const contractIndex = filenames.indexOf('0036_carddav_bidirectional_cleanup.sql');
const retentionIndex = filenames.indexOf('0037_carddav_conflict_retention.sql');
+ const multiBookIndex = filenames.indexOf('0038_carddav_multi_book.sql');
+ const writeTargetAliasIndex = filenames.indexOf('0039_carddav_write_target_alias.sql');
+ const publishIntentIndex = filenames.indexOf('0040_carddav_publish_intent.sql');
expect(duplicateVersions).toEqual([]);
expect(upstreamIndex).toBeGreaterThanOrEqual(0);
@@ -583,6 +627,9 @@ it('keeps migration versions unique and orders the CardDAV lifecycle migrations'
expect(expandIndex).toBe(incrementalIndex + 1);
expect(contractIndex).toBe(expandIndex + 1);
expect(retentionIndex).toBe(contractIndex + 1);
+ expect(multiBookIndex).toBe(retentionIndex + 1);
+ expect(writeTargetAliasIndex).toBe(multiBookIndex + 1);
+ expect(publishIntentIndex).toBe(writeTargetAliasIndex + 1);
});
describe('CardDAV schema migrations', () => {
@@ -1086,10 +1133,42 @@ describe('CardDAV schema migrations', () => {
WHERE user_id = $1 AND provider = 'carddav'
`, [userId]);
expect(contractedIntegration.config).not.toHaveProperty('dupMode');
+
+ await applyMigrations(client, '0038', '0038');
+ await expectMultiBookSchema(client);
+
+ // Existing single-book user: backfill preserves today's behavior exactly —
+ // the one book becomes the write-target and stays subscribed + lookup.
+ const { rows: [backfilledBook] } = await client.query(`
+ SELECT is_write_target, is_subscribed, is_lookup_source
+ FROM address_books WHERE id = $1
+ `, [earliestBookId]);
+ expect(backfilledBook).toEqual({
+ is_write_target: true,
+ is_subscribed: true,
+ is_lookup_source: true,
+ });
+
+ // CHECK rejects a write-target that is not subscribed.
+ await expect(client.query(`
+ UPDATE address_books SET is_write_target = true, is_subscribed = false
+ WHERE id = $1
+ `, [earliestBookId])).rejects.toMatchObject({ code: '23514' });
+
+ // Partial unique index rejects a second write-target for the same user.
+ const secondCarddavBookId = randomUUID();
+ await client.query(`
+ INSERT INTO address_books (
+ id, user_id, name, source, external_url, is_subscribed, is_lookup_source
+ ) VALUES ($1, $2, 'Second Book', 'carddav', $3, true, true)
+ `, [secondCarddavBookId, userId, `https://carddav.example.test/second/${userId}`]);
+ await expect(client.query(`
+ UPDATE address_books SET is_write_target = true WHERE id = $1
+ `, [secondCarddavBookId])).rejects.toMatchObject({ code: '23505' });
});
}, 120_000);
- it('creates the retained-conflict schema from migrations 0001 through 0037', async () => {
+ it('creates the multi-book publish-intent schema from migrations 0001 through 0040', async () => {
await withDatabase(databaseNames.fresh, async client => {
await assertMinimumPostgresVersion(client);
const freshUserId = randomUUID();
@@ -1108,7 +1187,7 @@ describe('CardDAV schema migrations', () => {
intervalMin: 45,
nested: { preserve: true },
})]);
- await applyMigrations(client, '0034', '0037');
+ await applyMigrations(client, '0034', '0040');
const { rows: [freshIntegration] } = await client.query(`
SELECT config
FROM user_integrations
@@ -1124,6 +1203,180 @@ describe('CardDAV schema migrations', () => {
});
await expectContractedBidirectionalSchema(client);
await expectConflictRetentionSchema(client);
+ await applyMigrations(client, '0038', '0038');
+ await expectMultiBookSchema(client);
+ await applyMigrations(client, '0039', '0039');
+ const addressBookColumns = await readColumns(client, 'address_books');
+ expect(addressBookColumns.discovery_alias_url).toEqual({
+ data_type: 'text',
+ is_nullable: 'YES',
+ column_default: null,
+ });
+ });
+ }, 120_000);
+
+ it('backfills the correct write-target per user by capability priority, then creation order', async () => {
+ const through0037Directory = await createMigrationDirectory('0001', '0037');
+ const migration0038Directory = await createMigrationDirectory('0038', '0038');
+ const migrationPool = new Pool({
+ connectionString: connectionStringFor(databaseNames.multiBookBackfill),
+ });
+ const priorityUserId = randomUUID();
+ const tieBreakUserId = randomUUID();
+ const allDeniedUserId = randomUUID();
+ // Later creation time, but 'allowed' — must win over an earlier 'unknown' book.
+ const allowedBookId = randomUUID();
+ const earlierUnknownBookId = randomUUID();
+ // Same-priority ('unknown') tie-break resolves by created_at, then id.
+ const earlierTieBookId = randomUUID();
+ const laterTieBookId = randomUUID();
+ // No create-capable book at all -> no write-target is assigned.
+ const deniedBookId = randomUUID();
+ const localBookId = randomUUID();
+
+ try {
+ await runMigrationsWithPool(migrationPool, through0037Directory);
+ await migrationPool.query(`
+ INSERT INTO users (id, username)
+ VALUES ($1, $4), ($2, $5), ($3, $6)
+ `, [
+ priorityUserId, tieBreakUserId, allDeniedUserId,
+ `carddav-priority-${priorityUserId}`,
+ `carddav-tiebreak-${tieBreakUserId}`,
+ `carddav-denied-${allDeniedUserId}`,
+ ]);
+ await migrationPool.query(`
+ INSERT INTO address_books (
+ id, user_id, name, source, external_url, remote_create_capability, created_at
+ ) VALUES
+ ($1, $6, 'Earlier Unknown', 'carddav', $7, 'unknown', '2026-01-01T00:00:00Z'),
+ ($2, $6, 'Later Allowed', 'carddav', $8, 'allowed', '2026-01-02T00:00:00Z'),
+ ($3, $9, 'Earlier Tie', 'carddav', $10, 'unknown', '2026-01-01T00:00:00Z'),
+ ($4, $9, 'Later Tie', 'carddav', $11, 'unknown', '2026-01-02T00:00:00Z'),
+ ($5, $12, 'Denied Only', 'carddav', $13, 'denied', '2026-01-01T00:00:00Z')
+ `, [
+ earlierUnknownBookId, allowedBookId, earlierTieBookId, laterTieBookId, deniedBookId,
+ priorityUserId, `https://dav.example.test/priority/unknown/${priorityUserId}`,
+ `https://dav.example.test/priority/allowed/${priorityUserId}`,
+ tieBreakUserId, `https://dav.example.test/tie/earlier/${tieBreakUserId}`,
+ `https://dav.example.test/tie/later/${tieBreakUserId}`,
+ allDeniedUserId, `https://dav.example.test/denied/${allDeniedUserId}`,
+ ]);
+ // A non-carddav (local) book must never be considered for the write-target.
+ await migrationPool.query(`
+ INSERT INTO address_books (id, user_id, name, source)
+ VALUES ($1, $2, 'Local Only', 'local')
+ `, [localBookId, priorityUserId]);
+
+ await runMigrationsWithPool(migrationPool, migration0038Directory);
+
+ const { rows: booksById } = await migrationPool.query(`
+ SELECT id, is_write_target, is_subscribed, is_lookup_source
+ FROM address_books
+ WHERE id = ANY($1::uuid[])
+ `, [[
+ earlierUnknownBookId, allowedBookId, earlierTieBookId,
+ laterTieBookId, deniedBookId, localBookId,
+ ]]);
+ const byId = Object.fromEntries(booksById.map(row => [row.id, row]));
+
+ // Capability priority: 'allowed' wins even though created later.
+ expect(byId[allowedBookId]).toEqual({
+ id: allowedBookId, is_write_target: true, is_subscribed: true, is_lookup_source: true,
+ });
+ expect(byId[earlierUnknownBookId]).toEqual({
+ id: earlierUnknownBookId, is_write_target: false, is_subscribed: true, is_lookup_source: true,
+ });
+
+ // Tie-break by creation order among equal-priority books.
+ expect(byId[earlierTieBookId]).toEqual({
+ id: earlierTieBookId, is_write_target: true, is_subscribed: true, is_lookup_source: true,
+ });
+ expect(byId[laterTieBookId]).toEqual({
+ id: laterTieBookId, is_write_target: false, is_subscribed: true, is_lookup_source: true,
+ });
+
+ // No create-capable book anywhere -> subscribed + lookup, but no write-target.
+ expect(byId[deniedBookId]).toEqual({
+ id: deniedBookId, is_write_target: false, is_subscribed: true, is_lookup_source: true,
+ });
+
+ // A local (non-carddav) book is untouched by the carddav-only backfill.
+ expect(byId[localBookId]).toEqual({
+ id: localBookId, is_write_target: false, is_subscribed: false, is_lookup_source: true,
+ });
+ } finally {
+ await migrationPool.end();
+ await rm(through0037Directory, { recursive: true, force: true });
+ await rm(migration0038Directory, { recursive: true, force: true });
+ }
+ }, 120_000);
+
+ // The non-regression guarantee of the publish-emailed-contacts setting: it
+ // ships OFF, so it may not un-publish anybody. Every contact that is explicit
+ // on the old schema is exporting today, and the backfill (publish_intent =
+ // NOT is_auto) is what keeps it exporting once publication is gated on intent.
+ // Only *new* explicit-by-email contacts land on the false default.
+ it('backfills publish intent from is_auto so existing explicit contacts keep exporting', async () => {
+ const through0039Directory = await createMigrationDirectory('0001', '0039');
+ const migration0040Directory = await createMigrationDirectory('0040', '0040');
+ const migrationPool = new Pool({
+ connectionString: connectionStringFor(databaseNames.publishIntentBackfill),
});
+ const userId = randomUUID();
+ const bookId = randomUUID();
+ const curatedId = randomUUID();
+ const emailedId = randomUUID();
+ const harvestedId = randomUUID();
+
+ try {
+ await runMigrationsWithPool(migrationPool, through0039Directory);
+ await migrationPool.query(
+ 'INSERT INTO users (id, username) VALUES ($1, $2)',
+ [userId, `carddav-publish-intent-${userId}`],
+ );
+ await migrationPool.query(
+ "INSERT INTO address_books (id, user_id, name, source) VALUES ($1, $2, 'Personal', 'local')",
+ [bookId, userId],
+ );
+ // The two explicit contacts are indistinguishable on the old schema — one
+ // was hand-created, one only ever emailed — and both export today. The
+ // backfill must carry both across, or the setting would silently drop a
+ // contact the user is already syncing.
+ await migrationPool.query(`
+ INSERT INTO contacts (id, address_book_id, user_id, uid, display_name, is_auto)
+ VALUES
+ ($1, $4, $5, 'curated-uid', 'Curated Contact', false),
+ ($2, $4, $5, 'emailed-uid', 'Emailed Sender', false),
+ ($3, $4, $5, 'harvested-uid', 'Harvested Sender', true)
+ `, [curatedId, emailedId, harvestedId, bookId, userId]);
+
+ await runMigrationsWithPool(migrationPool, migration0040Directory);
+
+ const { rows } = await migrationPool.query(`
+ SELECT id, is_auto, carddav_publish_intent
+ FROM contacts
+ WHERE user_id = $1
+ ORDER BY display_name
+ `, [userId]);
+ expect(rows).toEqual([
+ { id: curatedId, is_auto: false, carddav_publish_intent: true },
+ { id: emailedId, is_auto: false, carddav_publish_intent: true },
+ { id: harvestedId, is_auto: true, carddav_publish_intent: false },
+ ]);
+
+ // New rows land on the default — an emailed contact created after the
+ // migration is not published until the user says so.
+ const contactColumns = await readColumns(migrationPool, 'contacts');
+ expect(contactColumns.carddav_publish_intent).toEqual({
+ data_type: 'boolean',
+ is_nullable: 'NO',
+ column_default: 'false',
+ });
+ } finally {
+ await migrationPool.end();
+ await rm(through0039Directory, { recursive: true, force: true });
+ await rm(migration0040Directory, { recursive: true, force: true });
+ }
}, 120_000);
});
diff --git a/backend/src/services/carddavSync.db.test.js b/backend/src/services/carddavSync.db.test.js
index 38158cd..7ea396d 100644
--- a/backend/src/services/carddavSync.db.test.js
+++ b/backend/src/services/carddavSync.db.test.js
@@ -2,13 +2,14 @@ import { createHash, randomUUID } from 'node:crypto';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import pg from 'pg';
-import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import {
applyTestMigrations,
assertMinimumPostgresVersion,
createTestDatabase,
dropTestDatabase,
postgresTestContext,
+ quoteIdentifier,
waitForPostgresState,
} from './postgresTestHelpers.js';
@@ -1909,7 +1910,9 @@ describe('CardDAV full snapshot transaction', () => {
await expect(pending).resolves.toMatchObject({ ok: true, bookCount: 1 });
expect(mocks.fetchAddressBookDelta).toHaveBeenCalledOnce();
- expect(mocks.withTransaction).toHaveBeenCalledTimes(3);
+ // The initial apply, its footprint-changed retry, the batch-wide
+ // write-target claim, and finalization.
+ expect(mocks.withTransaction).toHaveBeenCalledTimes(4);
}, 120_000);
it('persists projection fingerprint from final eligible target tokens', async () => {
@@ -4089,3 +4092,682 @@ describe('CardDAV full snapshot transaction', () => {
}, 120_000);
});
+
+// Per-book summaries use an isolated database so their role fixtures do not
+// interfere with the shared transaction-test database.
+describe('CardDAV per-book summaries', () => {
+ const summaryDatabaseName = `carddav_book_summary_${process.pid}_${randomUUID()
+ .replaceAll('-', '').slice(0, 10)}`;
+ let summaryAdminClient;
+ let summaryClient;
+
+ beforeAll(async () => {
+ summaryAdminClient = new Client({ connectionString: databaseUrl });
+ await summaryAdminClient.connect();
+ await summaryAdminClient.query(`CREATE DATABASE ${quoteIdentifier(summaryDatabaseName)}`);
+ summaryClient = new Client({ connectionString: connectionStringFor(summaryDatabaseName) });
+ await summaryClient.connect();
+ await applyMigrations(summaryClient, '0038');
+ }, 120_000);
+
+ afterAll(async () => {
+ if (summaryClient) await summaryClient.end();
+ if (summaryAdminClient) {
+ await summaryAdminClient.query(
+ `DROP DATABASE IF EXISTS ${quoteIdentifier(summaryDatabaseName)} WITH (FORCE)`,
+ );
+ await summaryAdminClient.end();
+ }
+ }, 120_000);
+
+ it('reports per-book roles, capabilities, and materialized/lookup counts read-only', async () => {
+ mocks.query.mockImplementation((sql, params) => summaryClient.query(sql, params));
+ const userId = randomUUID();
+ const writeBookId = randomUUID();
+ const lookupBookId = randomUUID();
+ const writeBookUrl = `https://dav.example.test/summary/write/${userId}`;
+ const lookupBookUrl = `https://dav.example.test/summary/lookup/${userId}`;
+
+ await summaryClient.query(
+ 'INSERT INTO users (id, username) VALUES ($1, $2)',
+ [userId, `carddav-book-summary-${userId}`],
+ );
+ await summaryClient.query(`
+ INSERT INTO address_books (
+ id, user_id, name, source, external_url, created_at,
+ is_write_target, is_subscribed, is_lookup_source,
+ remote_create_capability, remote_update_capability, remote_delete_capability
+ ) VALUES
+ ($1, $3, 'Primary', 'carddav', $4, '2026-01-01T00:00:00Z',
+ true, true, true, 'allowed', 'allowed', 'allowed'),
+ ($2, $3, 'Apple Contacts', 'carddav', $5, '2026-01-02T00:00:00Z',
+ false, false, true, 'denied', 'denied', 'denied')
+ `, [writeBookId, lookupBookId, userId, writeBookUrl, lookupBookUrl]);
+ await summaryClient.query(`
+ INSERT INTO contacts (address_book_id, user_id, uid, display_name)
+ VALUES ($1, $2, 'contact-1', 'Ann Example')
+ `, [writeBookId, userId]);
+ await summaryClient.query(`
+ INSERT INTO carddav_remote_objects (
+ address_book_id, href, vcard, primary_email, mapping_status, lookup_display_name
+ ) VALUES ($1, '/ann.vcf', 'BEGIN:VCARD\r\nEND:VCARD\r\n', 'ann@example.test',
+ 'lookup', 'Ann Example')
+ `, [lookupBookId]);
+
+ const summaries = await carddavSync.getCarddavBookSummaries(userId);
+
+ expect(summaries).toEqual([
+ {
+ id: writeBookId,
+ name: 'Primary',
+ externalUrl: writeBookUrl,
+ isWriteTarget: true,
+ isSubscribed: true,
+ isLookupSource: true,
+ capabilities: { create: 'allowed', update: 'allowed', delete: 'allowed' },
+ materializedCount: 1,
+ lookupCount: 0,
+ lastSyncAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+ },
+ {
+ id: lookupBookId,
+ name: 'Apple Contacts',
+ externalUrl: lookupBookUrl,
+ isWriteTarget: false,
+ isSubscribed: false,
+ isLookupSource: true,
+ capabilities: { create: 'denied', update: 'denied', delete: 'denied' },
+ materializedCount: 0,
+ lookupCount: 1,
+ lastSyncAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+ },
+ ]);
+ });
+
+ it('reports an ignored book as serving neither the list nor lookup', async () => {
+ mocks.query.mockImplementation((sql, params) => summaryClient.query(sql, params));
+ const userId = randomUUID();
+ const ignoredBookId = randomUUID();
+ const ignoredBookUrl = `https://dav.example.test/summary/ignored/${userId}`;
+
+ await summaryClient.query(
+ 'INSERT INTO users (id, username) VALUES ($1, $2)',
+ [userId, `carddav-book-summary-ignored-${userId}`],
+ );
+ await summaryClient.query(`
+ INSERT INTO address_books (
+ id, user_id, name, source, external_url,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, $2, 'Ignored', 'carddav', $3, false, false, false)
+ `, [ignoredBookId, userId, ignoredBookUrl]);
+ // Ledger rows retained from when the book was still a lookup source; the
+ // next sync drops them, and until then they resolve no sender (the lookup
+ // probes filter on is_lookup_source), so the row must not advertise them.
+ await summaryClient.query(`
+ INSERT INTO carddav_remote_objects (
+ address_book_id, href, vcard, primary_email, mapping_status, lookup_display_name
+ ) VALUES ($1, '/stale.vcf', 'BEGIN:VCARD\r\nEND:VCARD\r\n', 'stale@example.test',
+ 'lookup', 'Stale Example')
+ `, [ignoredBookId]);
+
+ await expect(carddavSync.getCarddavBookSummaries(userId)).resolves.toMatchObject([{
+ id: ignoredBookId,
+ isWriteTarget: false,
+ isSubscribed: false,
+ isLookupSource: false,
+ materializedCount: 0,
+ lookupCount: 0,
+ }]);
+ });
+
+ it('returns an empty list for a user with no carddav books', async () => {
+ mocks.query.mockImplementation((sql, params) => summaryClient.query(sql, params));
+ const userId = randomUUID();
+ await summaryClient.query(
+ 'INSERT INTO users (id, username) VALUES ($1, $2)',
+ [userId, `carddav-book-summary-empty-${userId}`],
+ );
+
+ await expect(carddavSync.getCarddavBookSummaries(userId)).resolves.toEqual([]);
+ });
+});
+
+describe('CardDAV canonicalized-alias re-sync', () => {
+ const aliasDatabaseName = `carddav_alias_resync_${process.pid}_${randomUUID()
+ .replaceAll('-', '').slice(0, 10)}`;
+ let aliasAdminClient;
+ let aliasClient;
+
+ beforeAll(async () => {
+ aliasAdminClient = new Client({ connectionString: databaseUrl });
+ await aliasAdminClient.connect();
+ await aliasAdminClient.query(`CREATE DATABASE ${quoteIdentifier(aliasDatabaseName)}`);
+ aliasClient = new Client({ connectionString: connectionStringFor(aliasDatabaseName) });
+ await aliasClient.connect();
+ // Full schema, so discovery_alias_url exists and the alias-aware planning
+ // join, lock predicate, and reconciliation comparison run against real PG.
+ await applyMigrations(aliasClient, '0039');
+ }, 120_000);
+
+ afterAll(async () => {
+ if (aliasClient) await aliasClient.end();
+ if (aliasAdminClient) {
+ await aliasAdminClient.query(
+ `DROP DATABASE IF EXISTS ${quoteIdentifier(aliasDatabaseName)} WITH (FORCE)`,
+ );
+ await aliasAdminClient.end();
+ }
+ }, 120_000);
+
+ async function applyInTransaction(plan) {
+ await aliasClient.query('BEGIN');
+ try {
+ const result = await carddavSync.applyBookDelta(aliasClient, plan);
+ await aliasClient.query('COMMIT');
+ return result;
+ } catch (error) {
+ await aliasClient.query('ROLLBACK');
+ throw error;
+ }
+ }
+
+ it('applies a canonicalized book discovery still surfaces under its alias, in place', async () => {
+ const userId = randomUUID();
+ const generation = randomUUID();
+ const aliasUrl = `https://dav.example.test/addressbooks/${userId}/alias/`;
+ const canonicalUrl = `https://dav.example.test/addressbooks/${userId}/canonical/`;
+ const href = `${canonicalUrl}person.vcf`;
+
+ await aliasClient.query(
+ 'INSERT INTO users (id, username) VALUES ($1, $2)',
+ [userId, `alias-resync-${userId}`],
+ );
+ await aliasClient.query(
+ `INSERT INTO user_integrations (user_id, provider, config)
+ VALUES ($1, 'carddav', jsonb_build_object(
+ 'connectionGeneration', $2::text, 'contactCount', 1
+ ))`,
+ [userId, generation],
+ );
+ // Already canonicalized on an earlier sync: external_url holds the canonical
+ // URL, discovery_alias_url retains the alias the server keeps advertising.
+ const { rows: [book] } = await aliasClient.query(
+ `INSERT INTO address_books (
+ user_id, name, source, external_url, discovery_alias_url,
+ remote_sync_token, remote_sync_revision,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Aliased Lookup', 'carddav', $2, $3, 'token-1', 1,
+ false, false, true)
+ RETURNING id`,
+ [userId, canonicalUrl, aliasUrl],
+ );
+ await aliasClient.query(
+ `INSERT INTO carddav_remote_objects (
+ address_book_id, href, remote_etag, vcard, primary_email,
+ mapping_status, remote_semantic_hash, lookup_display_name
+ ) VALUES ($1, $2, 'old-etag', $3, 'person@example.test',
+ 'lookup', 'old-hash', 'Old Name')`,
+ [book.id, href, 'BEGIN:VCARD\r\nVERSION:3.0\r\nUID:person\r\nEND:VCARD\r\n'],
+ );
+
+ // Discovery returns the alias again; the delta reconciles to canonical.
+ const card = { ...remoteCard('person', 'person@example.test'), href };
+ const result = await applyInTransaction({
+ userId,
+ book: { url: aliasUrl, displayName: 'Aliased Lookup' },
+ connectionGeneration: generation,
+ expectedRemoteRevision: '1',
+ expectedRemoteToken: 'token-1',
+ nextRemoteToken: 'token-2',
+ capability: 'sync-collection',
+ replaceAll: true,
+ materialize: false,
+ collectionIdentity: { observedUrl: aliasUrl, canonicalUrl },
+ upserts: [card],
+ removedHrefs: [],
+ });
+
+ expect(result.bookId).toBe(book.id);
+
+ // The book advances in place — canonical URL and alias retained, token and
+ // revision moved — with no duplicate row inserted for the alias.
+ const { rows: books } = await aliasClient.query(
+ `SELECT id, external_url, discovery_alias_url, remote_sync_token,
+ remote_sync_revision::text AS remote_sync_revision
+ FROM address_books
+ WHERE user_id = $1 AND source = 'carddav'
+ ORDER BY id`,
+ [userId],
+ );
+ expect(books).toEqual([{
+ id: book.id,
+ external_url: canonicalUrl,
+ discovery_alias_url: aliasUrl,
+ remote_sync_token: 'token-2',
+ remote_sync_revision: '2',
+ }]);
+
+ const { rows: ledger } = await aliasClient.query(
+ `SELECT href, remote_etag, mapping_status, local_contact_id
+ FROM carddav_remote_objects
+ WHERE address_book_id = $1`,
+ [book.id],
+ );
+ expect(ledger).toEqual([{
+ href,
+ remote_etag: card.remoteEtag,
+ mapping_status: 'lookup',
+ local_contact_id: null,
+ }]);
+ }, 120_000);
+
+ it('reconciliation keeps a book seen only under its alias but still prunes a truly stale one', async () => {
+ const userId = randomUUID();
+ const aliasUrl = `https://dav.example.test/addressbooks/${userId}/rec-alias/`;
+ const canonicalUrl = `https://dav.example.test/addressbooks/${userId}/rec-canonical/`;
+ await aliasClient.query(
+ 'INSERT INTO users (id, username) VALUES ($1, $2)',
+ [userId, `alias-reconcile-${userId}`],
+ );
+ const { rows: [book] } = await aliasClient.query(
+ `INSERT INTO address_books (
+ user_id, name, source, external_url, discovery_alias_url, is_lookup_source
+ ) VALUES ($1, 'Reconcile', 'carddav', $2, $3, true)
+ RETURNING id`,
+ [userId, canonicalUrl, aliasUrl],
+ );
+
+ await aliasClient.query('BEGIN');
+ const kept = await carddavSync.reconcileStaleCarddavBooks(aliasClient, userId, {
+ contactCount: 0,
+ seenUrls: [aliasUrl],
+ });
+ await aliasClient.query('COMMIT');
+ expect(kept).toEqual([]);
+ const { rows: survivors } = await aliasClient.query(
+ 'SELECT id FROM address_books WHERE user_id = $1',
+ [userId],
+ );
+ expect(survivors).toEqual([{ id: book.id }]);
+
+ await aliasClient.query('BEGIN');
+ const removed = await carddavSync.reconcileStaleCarddavBooks(aliasClient, userId, {
+ contactCount: 0,
+ seenUrls: [],
+ });
+ await aliasClient.query('COMMIT');
+ expect(removed).toEqual([book.id]);
+ const { rows: afterRemoval } = await aliasClient.query(
+ 'SELECT id FROM address_books WHERE user_id = $1',
+ [userId],
+ );
+ expect(afterRemoval).toEqual([]);
+ }, 120_000);
+});
+
+// Per-book role management: patchCarddavBookRoles applies
+// Subscribe / Look-up-senders / write-target changes in one connection-fenced
+// transaction. Full role schema so the one-write-target index, the
+// write-target/subscribed CHECK, and the lookup ledger columns are all real.
+describe('CardDAV per-book role management', () => {
+ const roleDatabaseName = `carddav_book_roles_${process.pid}_${randomUUID()
+ .replaceAll('-', '').slice(0, 10)}`;
+ let roleAdminClient;
+ let roleClient;
+
+ beforeAll(async () => {
+ roleAdminClient = new Client({ connectionString: databaseUrl });
+ await roleAdminClient.connect();
+ await roleAdminClient.query(`CREATE DATABASE ${quoteIdentifier(roleDatabaseName)}`);
+ roleClient = new Client({ connectionString: connectionStringFor(roleDatabaseName) });
+ await roleClient.connect();
+ await applyMigrations(roleClient, '0039');
+ }, 120_000);
+
+ afterAll(async () => {
+ if (roleClient) await roleClient.end();
+ if (roleAdminClient) {
+ await roleAdminClient.query(
+ `DROP DATABASE IF EXISTS ${quoteIdentifier(roleDatabaseName)} WITH (FORCE)`,
+ );
+ await roleAdminClient.end();
+ }
+ }, 120_000);
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.query.mockImplementation((sql, params) => roleClient.query(sql, params));
+ mocks.withTransaction.mockImplementation(async callback => {
+ await roleClient.query('BEGIN');
+ try {
+ const result = await callback(roleClient);
+ await roleClient.query('COMMIT');
+ return result;
+ } catch (error) {
+ await roleClient.query('ROLLBACK');
+ throw error;
+ }
+ });
+ });
+
+ const GENERATION = 'role-generation';
+
+ async function seedRoleUser() {
+ const userId = randomUUID();
+ await roleClient.query('INSERT INTO users (id, username) VALUES ($1, $2)', [
+ userId, `carddav-roles-${userId}`,
+ ]);
+ await roleClient.query(
+ `INSERT INTO user_integrations (user_id, provider, config)
+ VALUES ($1, 'carddav', jsonb_build_object(
+ 'serverUrl', 'https://dav.example.test/',
+ 'username', 'role-user',
+ 'connectionGeneration', $2::text
+ ))`,
+ [userId, GENERATION],
+ );
+ return userId;
+ }
+
+ async function seedBook(userId, {
+ name,
+ write = false,
+ subscribed = false,
+ lookup = true,
+ create = 'allowed',
+ token = null,
+ }) {
+ const url = `https://dav.example.test/books/${randomUUID()}/`;
+ const { rows: [book] } = await roleClient.query(
+ `INSERT INTO address_books (
+ user_id, name, source, external_url, remote_sync_token,
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, $2, 'carddav', $3, $4, $5, 'allowed', 'allowed', $6, $7, $8)
+ RETURNING id, remote_sync_revision::text AS remote_sync_revision`,
+ [userId, name, url, token, create, write, subscribed, lookup],
+ );
+ return { id: book.id, url, remoteSyncRevision: book.remote_sync_revision };
+ }
+
+ async function bookRow(bookId) {
+ const { rows: [row] } = await roleClient.query(
+ `SELECT is_write_target, is_subscribed, is_lookup_source,
+ remote_sync_token, remote_sync_revision::text AS remote_sync_revision
+ FROM address_books WHERE id = $1`,
+ [bookId],
+ );
+ return row;
+ }
+
+ it('makeWriteTarget swaps the flag atomically and forces the new book subscribed', async () => {
+ const userId = await seedRoleUser();
+ const primary = await seedBook(userId, {
+ name: 'Primary', write: true, subscribed: true, lookup: true,
+ });
+ const apple = await seedBook(userId, {
+ name: 'Apple', write: false, subscribed: false, lookup: true, token: 'apple-token',
+ });
+
+ await carddavSync.patchCarddavBookRoles(
+ userId, apple.id, { makeWriteTarget: true }, GENERATION,
+ );
+
+ expect(await bookRow(apple.id)).toMatchObject({
+ is_write_target: true, is_subscribed: true, is_lookup_source: true,
+ });
+ // The previous holder keeps its contacts (still subscribed) but yields the flag.
+ expect(await bookRow(primary.id)).toMatchObject({
+ is_write_target: false, is_subscribed: true,
+ });
+ // Exactly one write-target survives the swap.
+ const { rows: targets } = await roleClient.query(
+ `SELECT id FROM address_books
+ WHERE user_id = $1 AND source = 'carddav' AND is_write_target = true`,
+ [userId],
+ );
+ expect(targets).toEqual([{ id: apple.id }]);
+ // The newly-subscribed book is scheduled for a full materializing re-pull.
+ const appleRow = await bookRow(apple.id);
+ expect(appleRow.remote_sync_token).toBeNull();
+ expect(appleRow.remote_sync_revision).not.toBe(apple.remoteSyncRevision);
+ }, 120_000);
+
+ it('rejects makeWriteTarget for a create-denied book and leaves roles unchanged', async () => {
+ const userId = await seedRoleUser();
+ const primary = await seedBook(userId, {
+ name: 'Primary', write: true, subscribed: true,
+ });
+ const readOnly = await seedBook(userId, {
+ name: 'Directory', write: false, subscribed: false, lookup: true, create: 'denied',
+ });
+
+ await expect(carddavSync.patchCarddavBookRoles(
+ userId, readOnly.id, { makeWriteTarget: true }, GENERATION,
+ )).rejects.toMatchObject({ code: 'ERR_CARDDAV_READ_ONLY' });
+
+ expect(await bookRow(readOnly.id)).toMatchObject({ is_write_target: false });
+ expect(await bookRow(primary.id)).toMatchObject({ is_write_target: true });
+ }, 120_000);
+
+ it('unsubscribe removes materialized contacts and demotes the ledger to lookup', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, {
+ name: 'Secondary', write: false, subscribed: true, lookup: true,
+ });
+ const { rows: [contact] } = await roleClient.query(
+ `INSERT INTO contacts (address_book_id, user_id, uid, display_name, primary_email)
+ VALUES ($1, $2, 'materialized-1', 'Materialized Person', 'mat@example.test')
+ RETURNING id`,
+ [book.id, userId],
+ );
+ await roleClient.query(
+ `INSERT INTO carddav_remote_objects (
+ address_book_id, href, remote_etag, vcard, primary_email,
+ local_contact_id, mapping_status, remote_semantic_hash, local_contact_hash
+ ) VALUES ($1, $2, '"etag-1"', $3, 'mat@example.test', $4, 'synced', 'hash', 'local-hash')`,
+ [book.id, `${book.url}mat.vcf`, 'BEGIN:VCARD\r\nEND:VCARD\r\n', contact.id],
+ );
+
+ await carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isSubscribed: false }, GENERATION,
+ );
+
+ expect(await bookRow(book.id)).toMatchObject({
+ is_write_target: false, is_subscribed: false, is_lookup_source: true,
+ });
+ const { rows: contacts } = await roleClient.query(
+ 'SELECT id FROM contacts WHERE address_book_id = $1', [book.id],
+ );
+ expect(contacts).toEqual([]);
+ const { rows: ledger } = await roleClient.query(
+ `SELECT mapping_status, local_contact_id, local_contact_hash, lookup_display_name
+ FROM carddav_remote_objects WHERE address_book_id = $1`,
+ [book.id],
+ );
+ expect(ledger).toEqual([{
+ mapping_status: 'lookup',
+ local_contact_id: null,
+ local_contact_hash: null,
+ lookup_display_name: 'Materialized Person',
+ }]);
+ }, 120_000);
+
+ it('a materializing pull that lost a race with unsubscribe demotes instead of resurrecting contacts', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, {
+ name: 'Racing', write: false, subscribed: true, lookup: true, token: 'race-token-1',
+ });
+ const href = `${book.url}race.vcf`;
+ const vcard = [
+ 'BEGIN:VCARD', 'VERSION:3.0', 'UID:race', 'FN:Race Contact',
+ 'EMAIL:race@example.test', 'END:VCARD', '',
+ ].join('\r\n');
+ const { rows: [contact] } = await roleClient.query(
+ `INSERT INTO contacts (address_book_id, user_id, uid, vcard, display_name, primary_email)
+ VALUES ($1, $2, 'race', $3, 'Race Contact', 'race@example.test')
+ RETURNING id`,
+ [book.id, userId, vcard],
+ );
+ await roleClient.query(
+ `INSERT INTO carddav_remote_objects (
+ address_book_id, href, remote_etag, vcard, primary_email,
+ local_contact_id, mapping_status, remote_semantic_hash, local_contact_hash
+ ) VALUES ($1, $2, '"race-1"', $3, 'race@example.test', $4, 'synced', 'sem', 'loc')`,
+ [book.id, href, vcard, contact.id],
+ );
+
+ // The user unsubscribes; the PATCH transaction commits first, removing the
+ // materialized contact and demoting the ledger to lookup.
+ await carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isSubscribed: false }, GENERATION,
+ );
+
+ // A sync already in flight still carries its pre-unsubscribe materialize
+ // decision and its stale (still-valid) token/revision fences. Applying it
+ // must honor the book's live is_subscribed under the shared integration
+ // lock — never re-import the contact the user just removed.
+ await roleClient.query('BEGIN');
+ try {
+ await carddavSync.applyBookDelta(roleClient, {
+ userId,
+ book: { url: book.url, displayName: 'Racing' },
+ connectionGeneration: GENERATION,
+ expectedRemoteRevision: book.remoteSyncRevision,
+ expectedRemoteToken: 'race-token-1',
+ nextRemoteToken: 'race-token-2',
+ capability: 'sync-collection',
+ replaceAll: false,
+ materialize: true,
+ collectionIdentity: null,
+ upserts: [{
+ href,
+ remoteEtag: '"race-1"',
+ vcard,
+ contact: { displayName: 'Race Contact', primaryEmail: 'race@example.test' },
+ }],
+ removedHrefs: [],
+ });
+ await roleClient.query('COMMIT');
+ } catch (error) {
+ await roleClient.query('ROLLBACK');
+ throw error;
+ }
+
+ const { rows: contacts } = await roleClient.query(
+ 'SELECT id FROM contacts WHERE address_book_id = $1', [book.id],
+ );
+ expect(contacts).toEqual([]);
+ const { rows: ledger } = await roleClient.query(
+ `SELECT mapping_status, local_contact_id
+ FROM carddav_remote_objects WHERE address_book_id = $1`,
+ [book.id],
+ );
+ expect(ledger).toEqual([{ mapping_status: 'lookup', local_contact_id: null }]);
+ expect(await bookRow(book.id)).toMatchObject({ is_subscribed: false });
+ }, 120_000);
+
+ it('rejects unsubscribing the write-target book', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, {
+ name: 'Primary', write: true, subscribed: true, lookup: true,
+ });
+
+ await expect(carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isSubscribed: false }, GENERATION,
+ )).rejects.toMatchObject({ code: 'ERR_CARDDAV_WRITE_TARGET_SUBSCRIBED' });
+
+ expect(await bookRow(book.id)).toMatchObject({ is_subscribed: true });
+ }, 120_000);
+
+ it('subscribing a lookup-only book schedules a full materializing reconcile', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, {
+ name: 'Apple', write: false, subscribed: false, lookup: true, token: 'apple-token',
+ });
+
+ await carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isSubscribed: true }, GENERATION,
+ );
+
+ const row = await bookRow(book.id);
+ expect(row).toMatchObject({ is_subscribed: true, is_lookup_source: true });
+ expect(row.remote_sync_token).toBeNull();
+ expect(row.remote_sync_revision).not.toBe(book.remoteSyncRevision);
+ }, 120_000);
+
+ it('turning off look-up-senders while unsubscribed leaves the book ignored', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, {
+ name: 'Apple', write: false, subscribed: false, lookup: true,
+ });
+
+ await carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isLookupSource: false }, GENERATION,
+ );
+
+ expect(await bookRow(book.id)).toMatchObject({
+ is_write_target: false, is_subscribed: false, is_lookup_source: false,
+ });
+ }, 120_000);
+
+ it('re-enabling look-up-senders on an ignored book schedules a full re-pull', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, {
+ name: 'Apple', write: false, subscribed: false, lookup: false, token: 'apple-token',
+ });
+
+ await carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isLookupSource: true }, GENERATION,
+ );
+
+ // An ignored book's ledger is dropped and never maintained, so resuming from
+ // the token it still carries would leave it lookup-on and empty forever.
+ const row = await bookRow(book.id);
+ expect(row).toMatchObject({ is_subscribed: false, is_lookup_source: true });
+ expect(row.remote_sync_token).toBeNull();
+ expect(row.remote_sync_revision).not.toBe(book.remoteSyncRevision);
+ }, 120_000);
+
+ it('fences a role change against a stale connection generation', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, { name: 'Apple', subscribed: false, lookup: true });
+
+ await expect(carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isSubscribed: true }, 'wrong-generation',
+ )).rejects.toMatchObject({
+ name: 'StaleCarddavPlanError', reason: 'connection-generation-changed',
+ });
+
+ expect(await bookRow(book.id)).toMatchObject({ is_subscribed: false });
+ }, 120_000);
+
+ it('rejects a role change with no fields and an unknown book', async () => {
+ const userId = await seedRoleUser();
+ const book = await seedBook(userId, { name: 'Apple', subscribed: false, lookup: true });
+
+ await expect(carddavSync.patchCarddavBookRoles(
+ userId, book.id, {}, GENERATION,
+ )).rejects.toMatchObject({ code: 'ERR_CARDDAV_BOOK_PATCH_EMPTY' });
+
+ await expect(carddavSync.patchCarddavBookRoles(
+ userId, randomUUID(), { isSubscribed: true }, GENERATION,
+ )).rejects.toMatchObject({ code: 'ERR_ADDRESS_BOOK_NOT_FOUND' });
+ }, 120_000);
+
+ it('rejects a role change when the connection is gone', async () => {
+ const userId = randomUUID();
+ await roleClient.query('INSERT INTO users (id, username) VALUES ($1, $2)', [
+ userId, `carddav-roles-none-${userId}`,
+ ]);
+ const { rows: [book] } = await roleClient.query(
+ `INSERT INTO address_books (user_id, name, source, external_url, is_lookup_source)
+ VALUES ($1, 'Orphan', 'carddav', $2, true) RETURNING id`,
+ [userId, `https://dav.example.test/books/${randomUUID()}/`],
+ );
+
+ await expect(carddavSync.patchCarddavBookRoles(
+ userId, book.id, { isSubscribed: true }, GENERATION,
+ )).rejects.toMatchObject({ name: 'StaleCarddavPlanError', reason: 'not-connected' });
+ }, 120_000);
+});
diff --git a/backend/src/services/carddavSync.integration.test.js b/backend/src/services/carddavSync.integration.test.js
index 85fc956..7a3888f 100644
--- a/backend/src/services/carddavSync.integration.test.js
+++ b/backend/src/services/carddavSync.integration.test.js
@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
import bcrypt from 'bcryptjs';
import express from 'express';
import pg from 'pg';
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
import { createCarddavFixtureServer } from './carddavFixtureServer.js';
import {
applyTestMigrations,
@@ -538,15 +538,22 @@ async function failureBoundaryState(userId) {
};
}
-async function seedConnectedUser(fixture, overrides = {}) {
+async function seedUser() {
const userId = randomUUID();
- const connectionGeneration = overrides.connectionGeneration || randomUUID();
- const password = overrides.password || 'fixture-password';
- const encryptedPassword = encrypt(password);
await databaseClient.query(
'INSERT INTO users (id, username) VALUES ($1, $2)',
[userId, `carddav-e2e-${userId}`],
);
+ return userId;
+}
+
+// Attach a CardDAV connection to an existing user. Split out of seedConnectedUser
+// so a test can create contacts *before* the connection exists — the local-only
+// create path — and then connect and let the sweep publish them.
+async function connectSeededUser(fixture, userId, overrides = {}) {
+ const connectionGeneration = overrides.connectionGeneration || randomUUID();
+ const password = overrides.password || 'fixture-password';
+ const encryptedPassword = encrypt(password);
const config = {
serverUrl: fixture.serverUrl,
username: overrides.username || 'fixture-user',
@@ -556,6 +563,11 @@ async function seedConnectedUser(fixture, overrides = {}) {
lastError: 'seeded-error',
bookCount: 0,
contactCount: 0,
+ // Left absent unless a test sets it: a connection stored without the key is
+ // exactly what every existing user has, and absent must mean OFF.
+ ...(overrides.publishEmailedContacts === undefined
+ ? {}
+ : { publishEmailedContacts: overrides.publishEmailedContacts }),
};
await databaseClient.query(`
INSERT INTO user_integrations (user_id, provider, config)
@@ -564,6 +576,27 @@ async function seedConnectedUser(fixture, overrides = {}) {
return { userId, config, connectionGeneration, encryptedPassword, password };
}
+async function seedConnectedUser(fixture, overrides = {}) {
+ return connectSeededUser(fixture, await seedUser(), overrides);
+}
+
+// Pre-designate a fixture connection's single book as the write target so a
+// test can exercise write routing in isolation, without first running the sync
+// whose first-connect bootstrap would assign the flag (that bootstrap is
+// covered end-to-end by the zero-config test below). This mirrors Slice 1's
+// migration backfill for an already-connected single-book user.
+async function seedWriteTargetBook(fixture, userId) {
+ const externalUrl = fixture.href('');
+ await databaseClient.query(`
+ INSERT INTO address_books (
+ user_id, name, source, external_url,
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Fixture Contacts', 'carddav', $2, 'allowed', 'allowed', 'allowed', true, true, true)
+ `, [userId, externalUrl]);
+ return externalUrl;
+}
+
function remoteVcard(uid, name, email = `${uid}@example.test`) {
return [
'BEGIN:VCARD',
@@ -681,8 +714,9 @@ async function seedMappedExplicitContact(fixture, userId) {
const { rows: [remoteBook] } = await databaseClient.query(`
INSERT INTO address_books (
user_id, name, source, external_url,
- remote_create_capability, remote_update_capability, remote_delete_capability
- ) VALUES ($1, 'Retry After Remote', 'carddav', $2, 'allowed', 'allowed', 'allowed')
+ remote_create_capability, remote_update_capability, remote_delete_capability,
+ is_write_target, is_subscribed, is_lookup_source
+ ) VALUES ($1, 'Retry After Remote', 'carddav', $2, 'allowed', 'allowed', 'allowed', true, true, true)
RETURNING id
`, [userId, fixture.href('')]);
const { rows: [row] } = await databaseClient.query(`
@@ -748,9 +782,60 @@ async function seedUnmappedExplicitContact(userId, {
const { rows: [row] } = await databaseClient.query(`
INSERT INTO contacts (
address_book_id, user_id, uid, vcard, etag, display_name,
- primary_email, emails, phones, additional_fields, is_auto
+ primary_email, emails, phones, additional_fields, is_auto, carddav_publish_intent
+ ) VALUES (
+ $1, $2, $3, $4, $5, $6, $7, $8::jsonb, '[]'::jsonb, '[]'::jsonb, false, true
+ )
+ RETURNING id
+ `, [
+ book.id,
+ userId,
+ uid,
+ card,
+ createHash('md5').update(card).digest('hex'),
+ displayName,
+ contact.emails[0].value,
+ JSON.stringify(contact.emails),
+ ]);
+ return { ...row, uid, card };
+}
+
+// An unmapped local contact — explicit by default (the export sweep's subject),
+// or `isAuto` to stand in for a harvested sender the sweep must pass over. Both
+// share one local book, as they do in a real mailbox.
+// `publishIntent` defaults to the migration's backfill rule (NOT is_auto), so an
+// "explicit" seed means a contact the user curated before this setting existed.
+// A contact that became explicit only by being emailed is seeded by passing
+// isAuto: false with publishIntent: false — exactly the row send.js leaves behind.
+async function seedUnmappedContact(userId, {
+ uid = randomUUID(),
+ displayName = 'Unmapped Explicit',
+ isAuto = false,
+ publishIntent = !isAuto,
+} = {}) {
+ const contact = {
+ uid,
+ displayName,
+ emails: [{ value: `${uid}@example.test`, type: 'other', primary: true }],
+ phones: [],
+ organization: null,
+ notes: null,
+ photoData: null,
+ additionalFields: [],
+ };
+ const card = generateVCard(contact);
+ const { rows: [book] } = await databaseClient.query(`
+ INSERT INTO address_books (user_id, name)
+ VALUES ($1, 'Unmapped Explicit Local')
+ ON CONFLICT (user_id, name) DO UPDATE SET updated_at = address_books.updated_at
+ RETURNING id
+ `, [userId]);
+ const { rows: [row] } = await databaseClient.query(`
+ INSERT INTO contacts (
+ address_book_id, user_id, uid, vcard, etag, display_name,
+ primary_email, emails, phones, additional_fields, is_auto, carddav_publish_intent
) VALUES (
- $1, $2, $3, $4, $5, $6, $7, $8::jsonb, '[]'::jsonb, '[]'::jsonb, false
+ $1, $2, $3, $4, $5, $6, $7, $8::jsonb, '[]'::jsonb, '[]'::jsonb, $9, $10
)
RETURNING id
`, [
@@ -762,6 +847,8 @@ async function seedUnmappedExplicitContact(userId, {
displayName,
contact.emails[0].value,
JSON.stringify(contact.emails),
+ isAuto,
+ publishIntent,
]);
return { ...row, uid, card };
}
@@ -842,7 +929,7 @@ async function seedTwoRemoteBooks(fixture, userId) {
nextToken: 'two-book-b-1',
});
expect(await carddavSync.syncUser(userId)).toMatchObject({
- ok: true, bookCount: 2, contactCount: 2,
+ ok: true, bookCount: 2, contactCount: 1,
});
const state = await projectionState(userId);
return {
@@ -975,11 +1062,186 @@ describe('production CardDAV HTTP to PostgreSQL 16', () => {
}
}, 120_000);
+ // Both halves of the sweep's contract in one pass. An explicit local contact
+ // still exports automatically — the bidirectional spec's "existing explicit
+ // contacts synchronize automatically" invariant, untouched by Slice 6 — while
+ // a harvested contact sitting right beside it is never swept out to the
+ // shared book. Only a deliberate promotion makes it explicit.
+ it('sweeps an explicit unmapped contact to the write-target and never a harvested one', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedConnectedUser(fixture);
+ await seedWriteTargetBook(fixture, seeded.userId);
+ const explicit = await seedUnmappedContact(seeded.userId, {
+ displayName: 'Explicit Sweep',
+ });
+ const harvested = await seedUnmappedContact(seeded.userId, {
+ displayName: 'Harvested Sweep',
+ isAuto: true,
+ });
+ fixture.queueSync('', { events: [], nextToken: 'sweep-token' });
+
+ try {
+ expect(await carddavSync.syncUser(seeded.userId)).toMatchObject({
+ ok: true,
+ exportFailures: [],
+ });
+
+ const put = fixture.requests.filter(request => request.method === 'PUT');
+ expect(put).toHaveLength(1);
+ expect(put[0].body).toContain('FN:Explicit Sweep');
+ expect(put[0].path).toBe(`/addressbooks/fixture-user/contacts/${explicit.uid}.vcf`);
+
+ const { rows: autoFlags } = await databaseClient.query(
+ 'SELECT id, is_auto FROM contacts WHERE user_id = $1 ORDER BY display_name',
+ [seeded.userId],
+ );
+ expect(autoFlags).toEqual([
+ { id: explicit.id, is_auto: false },
+ { id: harvested.id, is_auto: true },
+ ]);
+ const projection = await projectionState(seeded.userId);
+ expect(projection.ledger.map(row => row.local_contact_id)).toEqual([explicit.id]);
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
+ // send.js flips is_auto to false for anyone the user emails — upstream behavior
+ // the autocomplete ranking in routes/search.js depends on, so it stays. That
+ // makes is_auto the wrong gate for *publishing*: replying to a harvested sender
+ // would silently push them into the user's shared address book. Publication is
+ // gated on carddav_publish_intent instead, which only a deliberate act sets.
+ //
+ // The contact is is_auto = false and unmapped, so the old is_auto-only sweep
+ // would export it. Its false publication intent is the only thing keeping it
+ // local while the setting is off.
+ it('never publishes a contact that became explicit only by being emailed', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedConnectedUser(fixture);
+ await seedWriteTargetBook(fixture, seeded.userId);
+ const emailed = await seedUnmappedContact(seeded.userId, {
+ displayName: 'Emailed Sender',
+ isAuto: false,
+ publishIntent: false,
+ });
+ fixture.queueSync('', { events: [], nextToken: 'publish-off-token' });
+
+ try {
+ expect(await carddavSync.syncUser(seeded.userId)).toMatchObject({
+ ok: true,
+ exportFailures: [],
+ });
+
+ const put = fixture.requests.filter(request => request.method === 'PUT');
+ expect(put).toHaveLength(0);
+
+ const projection = await projectionState(seeded.userId);
+ expect(projection.ledger).toHaveLength(0);
+ // Unpublished, but still an explicit contact for autocomplete's purposes.
+ const { rows: [row] } = await databaseClient.query(
+ 'SELECT is_auto, carddav_publish_intent FROM contacts WHERE id = $1',
+ [emailed.id],
+ );
+ expect(row).toEqual({ is_auto: false, carddav_publish_intent: false });
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
+ // The opt-in: the "dedicated Email contacts book" workflow, where emailing
+ // someone is itself the act of adding them.
+ it('publishes an emailed contact when publishEmailedContacts is enabled', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedConnectedUser(fixture, { publishEmailedContacts: true });
+ await seedWriteTargetBook(fixture, seeded.userId);
+ const emailed = await seedUnmappedContact(seeded.userId, {
+ displayName: 'Emailed Sender',
+ isAuto: false,
+ publishIntent: false,
+ });
+ const harvested = await seedUnmappedContact(seeded.userId, {
+ displayName: 'Harvested Sender',
+ isAuto: true,
+ });
+ fixture.queueSync('', { events: [], nextToken: 'publish-on-token' });
+
+ try {
+ expect(await carddavSync.syncUser(seeded.userId)).toMatchObject({
+ ok: true,
+ exportFailures: [],
+ });
+
+ // The setting widens publication to emailed contacts only — a contact that
+ // was merely harvested from an inbound header is still not the user's.
+ const put = fixture.requests.filter(request => request.method === 'PUT');
+ expect(put).toHaveLength(1);
+ expect(put[0].path).toBe(`/addressbooks/fixture-user/contacts/${emailed.uid}.vcf`);
+ expect(put[0].body).toContain('FN:Emailed Sender');
+
+ const projection = await projectionState(seeded.userId);
+ expect(projection.ledger.map(row => row.local_contact_id)).toEqual([emailed.id]);
+ const { rows: [writeTarget] } = await databaseClient.query(`
+ SELECT id FROM address_books
+ WHERE user_id = $1 AND source = 'carddav' AND is_write_target = true
+ `, [seeded.userId]);
+ expect(projection.ledger[0].address_book_id).toBe(writeTarget.id);
+ const { rows: [row] } = await databaseClient.query(
+ 'SELECT is_auto FROM contacts WHERE id = $1',
+ [harvested.id],
+ );
+ expect(row).toEqual({ is_auto: true });
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
+ // A contact typed into MailFlow while CardDAV was disconnected is the plainest
+ // possible deliberate act, so connecting an account publishes it — the setting
+ // governs emailed contacts, never ones the user actually created.
+ it('publishes a manually created contact on connect with the setting off', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const userId = await seedUser();
+ const created = await carddavContactService.createContact(userId, {
+ displayName: 'Hand Written',
+ emails: [{ value: 'hand-written@example.test', type: 'work', primary: true }],
+ phones: [],
+ organization: null,
+ notes: null,
+ photoData: null,
+ additionalFields: [],
+ });
+ const seeded = await connectSeededUser(fixture, userId);
+ await seedWriteTargetBook(fixture, seeded.userId);
+ fixture.queueSync('', { events: [], nextToken: 'manual-create-token' });
+
+ try {
+ expect(await carddavSync.syncUser(seeded.userId)).toMatchObject({
+ ok: true,
+ exportFailures: [],
+ });
+
+ const put = fixture.requests.filter(request => request.method === 'PUT');
+ expect(put).toHaveLength(1);
+ expect(put[0].body).toContain('FN:Hand Written');
+ expect(put[0].path).toBe(`/addressbooks/fixture-user/contacts/${created.uid}.vcf`);
+
+ const projection = await projectionState(seeded.userId);
+ expect(projection.ledger.map(row => row.local_contact_id)).toEqual([created.id]);
+ } finally {
+ await fixture.close();
+ }
+ }, 120_000);
+
it('retains a fresh export Retry-After instead of clearing it from stale sync config', async () => {
const fixture = createCarddavFixtureServer();
await fixture.listen();
const seeded = await seedConnectedUser(fixture);
- const local = await seedUnmappedExplicitContact(seeded.userId, {
+ await seedWriteTargetBook(fixture, seeded.userId);
+ const local = await seedUnmappedContact(seeded.userId, {
displayName: 'Fresh Export Throttle',
});
await databaseClient.query(`
@@ -1062,6 +1324,7 @@ describe('production CardDAV HTTP to PostgreSQL 16', () => {
const fixture = createCarddavFixtureServer();
await fixture.listen();
const seeded = await seedConnectedUser(fixture);
+ await seedWriteTargetBook(fixture, seeded.userId);
const before = await failureBoundaryState(seeded.userId);
fixture.queueWrite('PUT', {
status: 429,
@@ -2141,6 +2404,7 @@ describe('production CardDAV HTTP to PostgreSQL 16', () => {
}, 120_000);
async function createPushOriginContact(fixture, userId, draft) {
+ await seedWriteTargetBook(fixture, userId);
const created = await carddavContactService.createContact(userId, {
firstName: null,
lastName: null,
@@ -3143,9 +3407,13 @@ describe('production CardDAV HTTP to PostgreSQL 16', () => {
ok: false,
error: 'forced second count book failure',
});
- expect(failedState.contacts).toHaveLength(1);
+ // Book A (the fresh connect's write-target) materialized person-a and its
+ // removal committed, leaving no materialized contacts; book B is the
+ // lookup-only sibling (person-b lives in the ledger only), and its failed
+ // apply rolled back, so its lone lookup row survives.
+ expect(failedState.contacts).toHaveLength(0);
expect(failedState.ledger).toHaveLength(1);
- expect(failedIntegration.config.contactCount).toBe(1);
+ expect(failedIntegration.config.contactCount).toBe(0);
fixture.reset();
fixture.queueDiscovery({ books: [
@@ -3162,10 +3430,12 @@ describe('production CardDAV HTTP to PostgreSQL 16', () => {
const retriedState = await projectionState(seeded.userId);
const [retriedIntegration] = await integrationState(seeded.userId);
- expect(retried).toMatchObject({ ok: true, contactCount: 1 });
- expect(retriedState.contacts).toHaveLength(1);
+ expect(retried).toMatchObject({ ok: true, contactCount: 0 });
+ // Book A stays empty; book B's retried lookup apply refreshes its single
+ // ledger row (person-b-2) without materializing a contact.
+ expect(retriedState.contacts).toHaveLength(0);
expect(retriedState.ledger).toHaveLength(1);
- expect(retriedIntegration.config.contactCount).toBe(1);
+ expect(retriedIntegration.config.contactCount).toBe(0);
await fixture.close();
}, 120_000);
@@ -3192,119 +3462,1139 @@ describe('production CardDAV HTTP to PostgreSQL 16', () => {
await fixture.close();
}, 120_000);
- it('snapshot discovery without sync-collection sends exactly one CardDAV filter', async () => {
+ it('claims the write-target for the best create-capable book of a fresh connect, not whichever is discovered first', async () => {
const fixture = createCarddavFixtureServer();
await fixture.listen();
const seeded = await seedConnectedUser(fixture);
- const href = fixture.href('snapshot-only.vcf');
- const card = remoteVcard('snapshot-only', 'Snapshot Only');
- fixture.putContact(href, '"snapshot-only-1"', card);
- fixture.queueDiscovery({ books: [{
- href: '/addressbooks/fixture-user/contacts/',
- displayName: 'Snapshot Only',
- reports: false,
- }] });
-
- expect(await carddavSync.syncUser(seeded.userId)).toEqual({
- ok: true,
- bookCount: 1,
- contactCount: 1,
- remote: 1,
- fetched: 1,
- updated: 1,
- removed: 0,
- fallback: 1,
- exportFailures: [],
+ const unknownPath = '/addressbooks/fixture-user/unknown-first/';
+ const allowedPath = '/addressbooks/fixture-user/allowed-second/';
+ const unknownUrl = new URL(unknownPath, fixture.serverUrl).href;
+ const allowedUrl = new URL(allowedPath, fixture.serverUrl).href;
+ const unknownHref = new URL('unknown-first.vcf', unknownUrl).href;
+ const allowedHref = new URL('allowed-second.vcf', allowedUrl).href;
+ fixture.queueDiscovery({ books: [
+ // Discovered *first*, but with unconfirmed ('unknown') create
+ // capability — claiming per book, in discovery order (the bug this
+ // proves fixed) would let this one keep the write-target forever.
+ { href: unknownPath, displayName: 'Unknown First', privileges: false },
+ // Discovered *second*, with confirmed ('allowed') create capability —
+ // the design's capability-priority backfill rule requires this one to
+ // win instead.
+ { href: allowedPath, displayName: 'Allowed Second' },
+ ] });
+ fixture.putContact(
+ unknownHref, '"unknown-first-1"', remoteVcard('unknown-first', 'Unknown First'),
+ );
+ fixture.putContact(
+ allowedHref, '"allowed-second-1"', remoteVcard('allowed-second', 'Allowed Second'),
+ );
+ fixture.queueSync('', {
+ events: [{ href: unknownHref, etag: '"unknown-first-1"' }],
+ nextToken: 'unknown-first-token',
});
- const state = await projectionState(seeded.userId);
- expect(state.books).toHaveLength(1);
- expect(state.books[0]).toMatchObject({
- source: 'carddav',
- remote_sync_token: null,
- remote_sync_capability: 'snapshot',
- remote_sync_revision: '1',
+ fixture.queueSync('', {
+ events: [{ href: allowedHref, etag: '"allowed-second-1"' }],
+ nextToken: 'allowed-second-token',
});
- expect(state.contacts).toHaveLength(1);
- expect(state.contacts[0].primary_email).toBe('snapshot-only@example.test');
- expect(state.ledger).toHaveLength(1);
- expect(fixture.counters).toMatchObject({
- requests: 4,
- propfind: 3,
- sync: 0,
- multiget: 0,
- addressbookQuery: 1,
- snapshotFilters: [1],
+
+ expect(await carddavSync.syncUser(seeded.userId)).toMatchObject({
+ ok: true, bookCount: 2, contactCount: 1,
});
+
+ const { rows: roles } = await databaseClient.query(`
+ SELECT external_url, is_write_target, is_subscribed, remote_create_capability
+ FROM address_books
+ WHERE user_id = $1 AND source = 'carddav'
+ ORDER BY external_url
+ `, [seeded.userId]);
+ expect(roles).toEqual([
+ {
+ external_url: allowedUrl,
+ is_write_target: true,
+ is_subscribed: true,
+ remote_create_capability: 'allowed',
+ },
+ {
+ external_url: unknownUrl,
+ is_write_target: false,
+ is_subscribed: false,
+ remote_create_capability: 'unknown',
+ },
+ ]);
await fixture.close();
}, 120_000);
- it('valid empty discovery prunes projection while malformed empty discovery changes only status', async () => {
- const emptyFixture = createCarddavFixtureServer();
- await emptyFixture.listen();
- const emptySeeded = await seedConnectedUser(emptyFixture);
- await seedSingleRemoteContact(emptyFixture, emptySeeded.userId);
- const unrelatedBook = await databaseClient.query(`
- INSERT INTO address_books (user_id, name)
- VALUES ($1, 'Empty Discovery Unrelated') RETURNING id, sync_token
- `, [emptySeeded.userId]);
- emptyFixture.reset();
- emptyFixture.queueDiscovery({ books: [] });
+ // ── Multi-book Slice 3: split pull-from-materialize ─────────────────────────
- expect(await carddavSync.syncUser(emptySeeded.userId)).toEqual({
- ok: true,
- bookCount: 0,
- contactCount: 0,
- remote: 0,
- fetched: 0,
- updated: 0,
- removed: 0,
- fallback: 0,
- exportFailures: [],
- });
- expect(await projectionState(emptySeeded.userId)).toEqual({
- books: [{
- id: unrelatedBook.rows[0].id,
- source: 'local',
- external_url: null,
- sync_token: unrelatedBook.rows[0].sync_token,
- remote_sync_token: null,
- remote_sync_capability: 'unknown',
- remote_sync_revision: '0',
- remote_projection_fingerprint: null,
- }],
- contacts: [],
- ledger: [],
- });
- const [emptyIntegration] = await integrationState(emptySeeded.userId);
- expect(emptyIntegration.config).toEqual({
- ...emptySeeded.config,
- lastError: null,
- lastSyncAt: expect.any(String),
- bookCount: 0,
- contactCount: 0,
- exportFailures: [],
+ async function bookRoles(userId) {
+ const { rows } = await databaseClient.query(`
+ SELECT external_url, is_write_target, is_subscribed, is_lookup_source
+ FROM address_books WHERE user_id = $1 AND source = 'carddav'
+ ORDER BY external_url
+ `, [userId]);
+ return rows;
+ }
+
+ async function ledgerRows(userId) {
+ const { rows } = await databaseClient.query(`
+ SELECT b.external_url, o.href, o.mapping_status, o.local_contact_id,
+ o.primary_email, o.lookup_display_name
+ FROM carddav_remote_objects o
+ JOIN address_books b ON b.id = o.address_book_id
+ WHERE b.user_id = $1
+ ORDER BY b.external_url, o.href
+ `, [userId]);
+ return rows;
+ }
+
+ it('first connect subscribes and materializes the write-target while a sibling defaults to lookup-only', async () => {
+ const fixture = createCarddavFixtureServer();
+ await fixture.listen();
+ const seeded = await seedConnectedUser(fixture);
+ const primaryPath = '/addressbooks/fixture-user/primary/';
+ const applePath = '/addressbooks/fixture-user/apple/';
+ const primaryUrl = new URL(primaryPath, fixture.serverUrl).href;
+ const appleUrl = new URL(applePath, fixture.serverUrl).href;
+ const primaryHref = new URL('primary.vcf', primaryUrl).href;
+ const appleHref = new URL('apple.vcf', appleUrl).href;
+ fixture.queueDiscovery({ books: [
+ { href: primaryPath, displayName: 'Primary' },
+ { href: applePath, displayName: 'Apple Contacts' },
+ ] });
+ fixture.putContact(primaryHref, '"primary-1"', remoteVcard('primary-person', 'Primary Person'));
+ fixture.putContact(appleHref, '"apple-1"', remoteVcard('apple-person', 'Apple Person'));
+ fixture.queueSync('', {
+ events: [{ href: primaryHref, etag: '"primary-1"' }],
+ nextToken: 'primary-token',
});
- expect(emptyFixture.counters).toMatchObject({
- requests: 3,
- propfind: 3,
- sync: 0,
- multiget: 0,
- addressbookQuery: 0,
+ fixture.queueSync('', {
+ events: [{ href: appleHref, etag: '"apple-1"' }],
+ nextToken: 'apple-token',
});
- await emptyFixture.close();
- const malformedFixture = createCarddavFixtureServer();
- await malformedFixture.listen();
- const malformedSeeded = await seedConnectedUser(malformedFixture);
- await seedSingleRemoteContact(malformedFixture, malformedSeeded.userId);
- const malformedBefore = await projectionState(malformedSeeded.userId, { timestamps: true });
- malformedFixture.reset();
- malformedFixture.queueDiscovery({
- rawBody: ' 
+ ) : (
+