Add private CardDAV synchronization and contact revision recovery
Build and publish container images / images (push) Successful in 13m39s
Release container images / release (push) Successful in 18s

This commit is contained in:
Anya Tokugawa committed 2026-11-02 08:41:15 +09:00
1 parent 433169c7e7
commit 19e12f96a8
32 files changed
+1855 -47

No files matched your search

+4 -1
View File
@@ -7,7 +7,10 @@
- [x] Add per-user defaults, accomplishment heatmap and opt-in daily SMTP task digest.
- [x] Add home search commands with project/calendar suggestions and explicit creation confirmation.
- [x] Add private contacts CRUD, trash/restore, vCard import/export and unknown-property preservation.
- [ ] Shared address books, CardDAV synchronization, work-record corrections and manual digest retry.
- [x] Add private CardDAV serving with isolated credentials, conditional writes, bounded reports and sync tokens; revision preview/restore and whole-book export (2026-11-02).
- [ ] Shared address books, external CardDAV connectors, physical-device compatibility, work-record corrections and manual digest retry.
See [CardDAV operation and limits](../operations/carddav-contacts.md). The private profile is not full CardDAV compliance; production rollout is tracked separately.
See [contracts and remaining scope](ja/task-productivity-contacts.md). These checks describe
the implemented slice; production rollout and test evidence are recorded separately.
+2 -2
View File
@@ -1,6 +1,6 @@
# 14. 予定・iCalendar・CalDAV・連絡先
状態:カレンダー部分は2026-09-22にローカル正本・Plan UI・限定CalDAVを実装開始。最新の契約・実装範囲・残作業は [カレンダー詳細設計](calendar-implementation.md) を参照。2026-11-01に個人アドレス帳のCRUD・vCard入出力・neomutt検索を実装した。[個人アドレス帳の実装契約](task-productivity-contacts.md)を以下の旧URI案より優先する。共有アドレス帳とCardDAV同期は引き続き設計案。
状態:カレンダー部分は2026-09-22にローカル正本・Plan UI・限定CalDAVを実装開始。最新の契約・実装範囲・残作業は [カレンダー詳細設計](calendar-implementation.md) を参照。2026-11-01に個人アドレス帳のCRUD・vCard入出力・neomutt検索、2026-11-02に個人CardDAV提供・履歴復元・一括exportを実装した。[個人アドレス帳の実装契約](task-productivity-contacts.md)と[CardDAV運用](../../operations/carddav-contacts.md)を以下の旧URI案より優先する。共有アドレス帳と外部CardDAV connectorは引き続き設計案。
## 四つのレイヤー
@@ -37,7 +37,7 @@ address bookの所有者・共有範囲、contact UUID、remote UID、複数メ
## URL/API案と実装順
人向けは `/v/organizer`、APIは `/_/api/v1/extension/organizer.{calendar|contacts}/…` を候補とします。**未実装・未予約**です。DAV提供面はroot discovery、認証、標準メソッドとルーターの衝突を調査してから決めます。Wiki PathをそのままDAV collectionにしません。
旧案の `/v/organizer` ではなく、連絡先の実装は `/v/plan/contacts`、APIは `/_/api/v1/extension/organizer.contacts/`、CardDAV提供面は `/_/api/v1/carddav/` を使います。Wiki PathをそのままDAV collectionにしません。以下の順序案のうち、個人アドレス帳と限定DAV提供は実装済み、共有と外部connectorは後続です。
1. ICS/vCard fixture、入出力preview、警告、重複防止。
2. local calendar/agenda・連絡先一覧、権限・version試験。
+3 -1
View File
@@ -4,7 +4,9 @@
## 優先順
2026-11-01:[タスク作成・作業記録・達成度・日次メール・個人アドレス帳](task-productivity-contacts.md)を追加。Web/CLI/neomuttの共通capture、時間記録、既定値、検索コマンドを接続。共有アドレス帳とCardDAV同期、作業記録の事後訂正、日次メールの再送・保持期間は同設計の後続範囲へ集約する。
2026-11-02:[個人CardDAV提供と履歴復元・一括export](../../operations/carddav-contacts.md)を実装。専用資格情報、条件付き更新、変更tokenと削除tombstone、bounded REPORTを追加。共有アドレス帳・外部CardDAV connector・実機互換確認は同資料の後続範囲。本番反映は別途管理する。
2026-11-01:[タスク作成・作業記録・達成度・日次メール・個人アドレス帳](task-productivity-contacts.md)を追加。Web/CLI/neomuttの共通capture、時間記録、既定値、検索コマンドを接続。作業記録の事後訂正、日次メールの再送・保持期間は同設計の後続範囲へ集約する。
2026-10-31:ユーザ指定により[日常操作・ブラウザ・エディタ・CLI](priority-ux-20261031.md)を次期開発の最優先とする。下記の従来機能追加より優先するが、認可・データ保全の安全条件は省略しない。TODO、受け入れ条件、復元用チェックポイントを同文書に集約する。
+4 -2
View File
@@ -64,13 +64,15 @@ vCard 3.0/4.0のUTF-8を対象とし、fold/unfold、テキストescape、複数
vCardの内容はDocumentStore snapshot、現在値と所有者・version・検索用projectionはSQLite、履歴はorganizer_contact_revisionsに保存する。DR snapshotのDocument参照抽出にも連絡先の現在・履歴を含める。一般のWiki/アセットURLに公開するための登録はしない。
2026-11-02に `organizer.contacts 0.2.0` として、個人CardDAV提供、変更履歴の確認・復元、全アドレス帳exportを追加した。履歴はGET `items/UUID/history` と `items/UUID/history/VERSION`、復元はPOST `items/UUID/restore` にrevision・version・If-Matchを渡し、新しい版を保存する。GET `export.vcf` は有効な連絡先のみ、最大5,000件・16 MiBを一括出力する。CardDAVのrootは `/_/api/v1/carddav/`。専用scope `contacts` を使い、既存CalDAVのallを拡張しない。[接続・同期・移行契約](../../operations/carddav-contacts.md)を参照。
## 移行と後続範囲
managed schemaにtask-productivityとcontactsを追加。task-productivityは既存organizer_items作成後に実行し、旧完了タスクを1回だけ集計projectionへ移す。既存スキーマ定義の改変ではない。切戻しでは旧版のschema checkが新コンポーネントを未知とするため、単に旧イメージを起動できるとは扱わない。データを消して戻さない。
- 連絡先の共有アドレス帳、CardDAV提供・外部双方向同期、重複候補mergeは別段階。今回の個人アドレス帳APIをCardDAV対応とは称さない。
- 連絡先の共有アドレス帳、外部CardDAV connector、重複候補mergeは別段階。個人CardDAV提供面と外部サービスの取り込みは区別する。
- 作業記録の事後修正・取消、失効Domainで取り残された記録の管理用終了手順、プロジェクト別集計、担当者への共有・通知は後続。
- 日次メールの手動再送・配信ログの保管期間、receiptの失効設計は後続。安易な削除で重複作成・配信を復活させない。
- 連絡先履歴の画面復元・アドレス帳一括export、vCard legacy変換は後続。
- vCard legacy変換・version間変換と履歴保持期間は後続。
利用手順は [neomuttとタスクCLI](../../operations/neomutt-tasks.md) を参照。
+117
View File
@@ -0,0 +1,117 @@
# 個人アドレス帳の操作とCardDAV接続
`organizer.contacts 0.2.0` は、Webの個人アドレス帳と外部クライアントが同じ連絡先を編集するための限定CardDAV提供面を持つ。連絡先はDomainと所有者で分離し、管理者であることだけでは他人の連絡先を取得できない。共有アドレス帳や、PagesWikiから外部サービスを定期取得するconnectorは別の後続機能である。
この資料は実装済みのソース契約を示す。本番反映はリリース・展開記録で別に管理する。
## Webでの操作
入口は `/v/plan/contacts`。
- 名前、複数メールアドレス・電話番号、所属、メモを編集する。
- 「削除済み」の一覧から連絡先を復元する。削除は履歴を残す論理削除である。
- 個別の「変更履歴」で過去のvCardを確認し、選んだ版を新しい版として復元する。復元確認で未保存フォームの破棄を明示する。他の端末で変更されていた場合は412で止まり、再読み込みが必要になる。
- 「アドレス帳を書き出す」で有効な連絡先を1つの `.vcf` にまとめる。削除済みは含まない。上限は5,000件または16 MiBで、超過した場合は途中までのファイルを正常応答として返さない。
- ⇄ の「CardDAV連携」で、端末別の資格情報を発行・失効する。
vCardの未対応項目は保存・再出力するが、Webで変更した項目についてはその項目のTYPEなどのparameterを再現しない。PHOTO等の外部URLにはアクセスしない。vCard 2.1、ENCODING/CHARSET指定、1件64 KiBを超える画像入りカードなどは拒否する。詳細は[個人アドレス帳の実装契約](../design/ja/task-productivity-contacts.md)を参照。
## クライアントを接続する
1. Webに通常ログインし、連絡先画面の ⇄ を開く。
2. 端末名、読み取り専用または読み書き、有効期間を選び、パスワードを発行する。
3. 表示された認証情報IDとパスワードをクライアントに保存する。パスワードは再表示できない。
| 項目 | 値 |
| --- | --- |
| サーバーURL | `https://pages.anya.jp/_/api/v1/carddav/`。別DomainではそのDomainのHTTPS originを使う |
| ユーザー名 | 発行画面の認証情報ID。Wikiのユーザー名・メールアドレスではない |
| パスワード | 発行した連絡先専用パスワード |
| アドレス帳 | 自動検出される `PagesWiki Contacts` |
| discovery | `/.well-known/carddav` からAPI rootへ307転送 |
専用資格情報のscopeは `contacts`。既存の `tasks`、`calendar`、`all` は連絡先への権限を持たず、`all` の意味は予定とタスクのままである。連絡先の資格情報からWiki API、予定、タスクへアクセスできない。通常セッションのBearerでも本人のCardDAVを操作できるが、端末設定には用途を限定した資格情報を使う。
資格情報の管理は既存の `/_/api/v1/caldav-credentials` APIを共用する。作成時に `scope: "contacts"` を明示する。この管理API自体には通常のログインセッションが必要で、CardDAV資格情報による再発行はできない。HTTPSを必須とし、AuthorizationやvCard本文をログ・問い合わせに貼り付けない。
vdirsyncer 0.21.0では、合成データによる検出、取得、双方からの更新、新規作成、双方からの削除を検証した。設定例は以下の通り。実際の資格情報を含むファイルは所有者のみ読み取り可能にする。
```ini
[general]
status_path = "~/.local/state/vdirsyncer"
[pair contacts]
a = "contacts_local"
b = "contacts_remote"
collections = ["contacts"]
[storage contacts_local]
type = "filesystem"
path = "~/.local/share/contacts"
fileext = ".vcf"
[storage contacts_remote]
type = "carddav"
url = "https://pages.anya.jp/_/api/v1/carddav/"
username = "発行された認証情報ID"
password = "発行されたパスワード"
```
`contacts_local` のpath配下に `contacts` ディレクトリを作り、`vdirsyncer discover`、`vdirsyncer sync` を実行する。アドレス帳名の書き換えは未対応なので、`metadata = ["displayname"]` によるmetasyncは設定しない。全件削除はクライアントの安全機構が止める場合があり、意図した削除か確認するまで強制オプションを使わない。DAVx⁵・iOSの端末実機での検証は別途必要である。
## URIと通信契約
| URI | 役割と操作 |
| --- | --- |
| `/_/api/v1/carddav/` | OPTIONS、PROPFIND。current-user-principalとaddressbook-home-set |
| `/_/api/v1/carddav/{principal_uuid}/` | 本人のhome。OPTIONS、PROPFIND |
| `/_/api/v1/carddav/{principal_uuid}/contacts/` | 固定の個人アドレス帳。OPTIONS、PROPFIND、REPORT |
| 同上の `{resource_name}.vcf` | OPTIONS、PROPFIND、GET、HEAD、PUT、DELETE |
resource名は `.vcf` を含め5〜128 ASCII bytes、英数字・ハイフン・アンダースコア・ピリオドのみ、先頭ピリオドは禁止。Web作成分はUUID.vcf、クライアント作成分は受信した名前を固定対応表に保存する。UIDは同じ所有者・Domain内で一意かつ作成後は変更不可。名前とUIDが同じという仮定はしない。
取得時のETagはリソースのversionを表す。作成は `If-None-Match: *`、更新・削除は取得済みの `If-Match` が必要で、条件がない場合は428、競合時は412を返す。内容の正規化でPUTの入力バイト列と保存値が変わった場合は、PUT応答にETagを付けず再取得を要求する。vCardのUID欠落・変更・重複を黙って別人として保存しない。
PROPFINDはDepth 0または1。アドレス帳一覧は同じDB snapshotからtokenとメタデータを取得し、本文をロードせず最大5,000件を返す。上限超過は507で、欠落した一覧からクライアントが削除を誤推定することを避ける。
REPORTは以下の限定範囲を実装する。
- `addressbook-multiget`:同じアドレス帳の最大100 href。外部URLは取得しない。
- `addressbook-query`:最大200件のアドレス帳を対象とするbounded scan。propertyの存在・不在、text-match、anyof/allofを扱う。未知propertyも原文から検索する。parameter filterは未対応で、無視せずエラーにする。
- `sync-collection`:sync-level 1。最大200件ずつの差分、追加・更新・削除tombstoneを返す。続きがある場合はアドレス帳の507応答と次のtokenを207内に含める。クライアントはそのtokenで続行する。
不正なsync-tokenは403の `valid-sync-token`。クライアントはローカルデータを捨てず、再照合する。XMLは64 KiB、深さ12、要素1,000まででDTDを拒否する。全体の処理期限は20秒。取得・更新は `private, no-store` とする。
対応するvCardは既存のUTF-8 3.0/4.0保存profileで、通信では保存されたversionをそのまま返す。3.0↔4.0変換やaddress-dataの部分抽出はしない。別versionを明示要求された場合は拒否する。MKCOL、PROPPATCH、DAV ACL、共有・複数アドレス帳、MOVE/COPYは未対応。`DAV: 1, addressbook-access` はクライアント検出用に返すが、CardDAV全機能への準拠を意味しない。応答には `X-PagesWiki-CardDAV-Profile: private-addressbook` を付ける。
基本プロトコルは[RFC 6352](https://www.rfc-editor.org/rfc/rfc6352.html)、差分同期は[RFC 6578](https://www.rfc-editor.org/rfc/rfc6578.html)を参照する。text-matchは `i;octet` と、titlecase後の互換分解を使う `i;unicode-casemap` を扱う。[RFC 5051](https://www.rfc-editor.org/rfc/rfc5051.html)
## 保存と移行
contactsのmanaged schema v2を追加し、リリース済みv1の定義は変更しない。既存の連絡先と履歴を残したままresource名、変更sequence、DB epochを補う。変更sequenceは連絡先ごとの最新1行だけを保持し、論理削除も差分に残す。vCard snapshotと履歴の保管は従来通りであり、履歴自体の保持期間・GCは後続設計となる。
sync-tokenはDB epoch、Domain、所有者、sequenceに結び付く。DBバックアップを復元するとsequenceが過去へ戻り得るため、復元先を公開する前に停止状態で `organizer_contact_epoch` のvalueを新しい32-byte乱数のhexへ更新し、既存クライアントを再照合させる。tombstoneを物理削除する保守もtoken失効とセットで設計する。通常稼働中の自動purgeは実装しない。
切戻しには旧バイナリが新schema versionを拒否する場合がある。旧イメージへの交換だけを安全なrollbackとは扱わず、整合したDB・DocumentStoreのバックアップと復元手順を用意する。新しい連絡先秘密値は `pw_contactdav_` prefixを使い、旧版がタスク権限として誤解釈しない。
## 検証
2026-11-02に以下を合成データで実施した。本番連絡先や外部取り込みカレンダーの内容は検証に使用していない。
- `go test ./... -count=1`、`go vet ./...`。
- 連絡先・managed schemaのrace detector付きテスト。同時PUTは一方だけ204、他方は412となる。
- v1からv2への既存行保全・繰り返し起動、変更sequence更新、資格情報削除のmarker清掃。
- 読み取り専用・失効・別scope・extension無効化、カレンダーとタスクを無効にした場合の独立稼働。
- 201件の一覧と差分ページング、上限超過の明示、XML・UID・文字コード・Unicode検索の境界条件。
- vdirsyncer 0.21.0での往復同期、Chromiumのデスクトップとスマートフォン幅での保存・履歴確認・復元・一括export・資格情報発行と失効。
実クライアント試験は `PAGESWIKI_VDIRSYNCER` に実行ファイルを指定し、`go test ./internal/server -run '^TestContactDAVVdirsyncer$' -count=1` で再実行できる。ブラウザ試験は `PAGESWIKI_BROWSER_TEST=1` で `TestProductivityChromium` の `contacts-` サブテストを実行する。通常のテストでは外部クライアントとブラウザの試験をskipする。
## 次段階
- [ ] 複数・共有アドレス帳、read/write collaboratorと共有解除、管理者の代理操作境界。
- [ ] 外部CardDAV connector。ETagと同期receipt、競合保全、URLのSSRF対策、イベントキュー・停止スイッチ。
- [ ] 200件を超えるaddressbook-queryの索引化、parameter filter、vCard version変換の情報保持試験。
- [ ] 端末実機の互換試験、連絡先mergeの確認UI、履歴保持・削除ポリシー。
後続機能は現在の個人アドレス帳を暗黙に公開・共有しない。外部connectorの追加は資格情報の保存・外向き通信を新たに伴うため、現在のCardDAV提供面とは別の設定とする。