laoyang/FamilyBook
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

v24 第 22 批：名册加 CardDAV 同步 + 一把通用 DAV 口令（日历与通讯录共用）

Browse Source 
用户 2 条原话：
  ①「名册，增加cardav同步功能。」
  ②「caldav和cardav，都增加一个创建口令的功能，这样，就使用用户名和口令来同步，
     避免在第三方客户端进行同步时自己的密码泄露。」

用户拍板的两个岔路（AskUserQuestion）：
  · 口令范围 = **一把通用 DAV 口令**（日历 + 通讯录共用），不是两个 ——
    手机上填一次就都通；两把会让用户要在两个页面各配一遍、还容易只配一半。
  · 同步范围 = 与**名册页完全一致**（Person::roster(kind='member')），不另发明判据。

════ 一、 口令统一：caldav_credentials → dav_credentials（Schema v23）════
表**改名**（不是新建一张 carddav_credentials）：
  · 老站 RENAME → 已配好的口令一字不动，**所有设备不用重配**；
  · 新装时两表都不在 → 跳过（直接 RENAME 一张不存在的表会抛异常、把升级打断）；
  · 两表并存（上次升级跑一半 / 有人手工建过）→ 搬行（INSERT IGNORE）+ DROP 旧表。
⚠️ 迁移**必须**是 RENAME + 存在性守卫（新增 Schema::hasTable），
   只改建表语句里的名字的话，老库会**再建一张空表**、旧表留在原地没人读 →
   用户所有已配好的同步设备立刻全部 401（而且改密码也修不好：新口令写进了新表）。

Auth：caldavIssue/Revoke/Auth/hasCalDav → davIssue/davRevoke/davAuth/hasDav，
新增 davLastUsed()（UI 上显示"最近使用"）。

口令管理入口搬到**个人设置 → DAV 同步**（它管的是"我的凭据"，同时服务日历与通讯录；
放在日历页会让只想同步通讯录的人在日程里找半天）。
  · 旧路由 calendar/caldav_token|caldav_revoke 保留为 302 → 老书签不 404；
  · 日历本页只留地址 + 一个指路按钮（密码类的东西只该有一个管理入口，
    两处各放一套按钮迟早对不上：这页重置了、那页还显示"已配置"）。

════ 二、 CardDAV（全新）════
· app/Vcard.php —— 名册 → vCard **3.0**（iOS/DAVx⁵ 推荐；4.0 在 iOS 上会被降级丢字段）。
  FN 必须有（缺了 iOS 会**整张卡丢掉**）、UID 用 person id（稳定，不随改名变）、
  标签能对上固定词就走 TYPE（手机上显示成"手机/工作"），对不上就原样放进
  X-ABLabel（**不猜**成 HOME —— 猜错了用户看到"家"其实是"奶奶家"）。
· app/CardDav.php —— books/rows/one/cardOf/etag/parsePath；ROOT='/carddav/'。
· carddav.php —— OPTIONS / PROPFIND(0,1) / GET / REPORT；**写方法一律 403**。
  只读是与 CalDAV 同样的取舍：与其"半支持"（客户端以为改成功了、服务端却没落库），
  不如明确拒绝，用户至少知道"手机上加的联系人不会同步回来"。
· **地址空间分离、鉴权同一套**：/carddav/ 与 /dav/ 各自独立（资源类型与命名空间
  完全不同，混在一棵树里要靠猜客户端意图，猜错的表现是"连上了但一本都看不到"）；
  但两者调**同一个** Auth::davAuth、读**同一张** dav_credentials 表 ——
  这正是"一把口令管两种同步"的落点，也保证不会出现"日历能连、通讯录连不上"。
· 路由三处：router.php（本地 php -S）+ .htaccess（书面来源）+ 部署脚本 5c 段。
  ⚠️ 线上用**独立标记块** `# >>> FamilyBook CardDAV`：老站已经有
  `# >>> FamilyBook CalDAV`，把新规则并进那一段会被"标记在不在"的幂等判断
  **整段跳过** → /carddav/ 永远 404，而本地（走 router.php）完全正常。
· 打包白名单加 carddav.php（站点根下的独立入口最容易漏 —— dav.php / upload_stage.php
  都漏过一次，症状都是"线上那个功能 404、本地一切正常"）。

════ 三、 🔴 三个真 bug（全是"本地校验全绿"型，靠 vCard 往返测试抓出来）════
把 App\Vcard（导出）与 App\ContactImport（导入）各自单测都是绿的，
但**导出→导入跑一遍**立刻翻出三个：

 ① Vcard::fold **漏了"续行补前导空格"**（照抄 Ics::fold 时抄漏了最后一步）。
    后果：折出来的那几段变成**独立的属性行** → 客户端把半个名字/半个地址当垃圾丢掉。
    而"每行 ≤75 字节""确实折行了"全是绿的 —— 只有「**折行可无损还原**」这条断言能抓。

 ② ContactImport 用 `explode(';')` 给 ADR / N 分段 —— PHP 的 explode **不认识转义**，
    值里写了 `\;`（字面分号）照样在那里拆开 → 地址「青岛市,市南区;某某路1号」被
    从中间切断，后半截（含省名）跑到别的段上；导进来的人地址只剩前半句、
    而且看着像"省没填"。手机通讯录里带分号的地址（"XX路1号;3单元")不算罕见。
    → 新增 `splitVcardSegments()`：**按未转义的分号**切，切完再逐段 unescape。
    ⚠️ "先 unescape 再分段"是同一个错的另一种写法（本轮第一版就这么改，往返照样红）。

 ③ Vcard::adrField 的**分号数量对、但位置错一位**（省落到了"邮编"格）。
    第一版 `;;` + 街道 + `;;;` + 省 + `;` —— 总数也是 6，可多出来的那个挤在前面 →
    解析器读段 4 拿到空串。**段数对、总数对、只有位置错一位**，
    所以"数分号个数"的检查发现不了它。

════ 四、 顺带修的一个 ETag 一致性 bug ════
同一张卡在 PROPFIND（清单）与 REPORT（取正文）里原本算出**两个不同的 ETag**
（一个用不带结尾 CRLF 的正文、一个用带 CRLF 的）→ 客户端认为这张卡一直在变、
**反复重拉**（同步永远不收敛），而服务端看不出任何异常（两边都合法）。
→ 新增 `CardDav::cardOf()`，把**正文与 ETag 成对返回**，结尾 CRLF 只加在正文上、
不参与 ETag。修法不是"两处改成一样"，而是**让它们没有机会不一样**。

════ 五、 UI ════
· 个人设置页「DAV 同步」卡：两个地址（/dav/ 与 /carddav/）+ 用户名预填 + 一次性明文
  （只显示这一次，走一次性会话槽位）+ 生成/重置/撤销 + "最近使用"。
· 名册页 CardDAV 卡：地址 + "这 N 个人"（人数与名册页一致，用户当场能对上）+
  指路口令的按钮。**不放**生成表单。
· 日历本页改口径：只留 /dav/ 地址 + 指路链接。

════ 六、 验证 ════
- e2e **1106/0**（本批新增约 45 条：CardDAV 全协议、越权 404、只读 403、
  一把口令开两把锁、撤销后两处**同时**失效、口令一次性/不落库、ETag 一致性）
- **vCard 规格体检 36/36**（新工具 `_fb_b22_vcf_spec.php`：转义/折行/多值/标签/
  空名兜底 + **导出→导入往返一致**）
- **真机探针 28/0**（新工具 `_fb_b22_ui.py`：两块 UI 渲染、**在浏览器里点按钮**生成
  口令、刷新后明文消失但状态留下、名册页人数对得上、日历本页改口径、
  撤销后两处 401、全程零 JS 报错）
- 桌面几何 428/0 · 移动端几何（360/375/390/414）684/0 · 结构升级 149/0
- 部署静态断言空跑 **307/0** · 线上部署 134 项自检 0 失败
- **反向验证 14/14**（`_fb_b22_falsify.py`）：迁移不干活 / 读旧表 / 断入口 /
  去掉 addressbook 声明 / 只读守卫失效 / 不校验口令 / 越权不再查名册 /
  折行不补空格 / 分段改回 explode / ADR 错位 / UI 卡拿掉 / 明文不再一次性 /
  撤销不删凭据 —— 逐条改回旧行为，对应断言都变红，还原后复绿。

════ 七、 🔴🔴 线上实测挖出的**最重要**的一条：DAV 鉴权在 Apache 上一直是坏的 ════
部署后在线上以 **Web 用户(www)** 身份做端到端验收时，DAV 全部 401 ——
而本地 e2e 全绿。追下去发现两层原因：

 ① **测试假象**：我把 DAV 请求放进了一个**临时探针文件**里，用 `curl` 打它。
    但 Apache 请求 `.php` 文件时**不套用站点根 .htaccess 的 URL 重写** ——
    所以探针里的请求根本没被转给 dav.php/carddav.php，拿到的是**探针自己的 401**，
    不是 DAV 的。第一轮"全 401"有一半是探针自己造的假象。

 ② **真问题**：Apache 默认**不把 `Authorization` 头交给 PHP-FPM** ——
    `$_SERVER['PHP_AUTH_USER']` 与 `HTTP_AUTHORIZATION` **全是 null**。
    实测（这台服务器 Apache 2.4.53，直接监听 80/443，**没有 nginx**）：
        基线            : {"PHP_AUTH_USER":null,"HTTP_AUTHORIZATION":null}
        `CGIPassAuth On`: {"PHP_AUTH_USER":"abc","HTTP_AUTHORIZATION":"(有)"}
    ⇒ **线上 CalDAV 从来没被真实客户端连上过**（服务端代码是对的、环境少了这一行）。
      本轮 e2e 用 `php -S`，那里 `PHP_AUTH_USER` 是**自己填好的**，所以一路全绿 ——
      又一个"本地好好的、线上不行"。

  修法：部署脚本 5c 段追加**独立标记块** `# >>> FamilyBook DAV auth`，内容
  `CGIPassAuth On`（Apache **2.4.13+ 的核心指令**，不需要额外模块、**不用动宝塔面板**）。
  仓库 `.htaccess` 同步写上（它是那段规则唯一的书面来源）。

  修完后线上端到端**全部通过**（以 www 身份、真实 HTTP 服务、真实数据）：
    · CalDAV：`PROPFIND → 207`、**8 本日历本**、`PUT → 403`
    · CardDAV：根 `207` + `<card:addressbook/>`；清单 `207`、**1089 张卡**、1089 个 ETag；
      整本 vcf `200`、1089 张、全是 3.0、`text/vcard`；**最长行 75 字节**（真实数据上
      折行真的发生了）；`REPORT → 207` 带 `address-data`；`PUT → 403`；
      `OPTIONS → 200 DAV: 1, 2, 3, addressbook`
    · 导出的卡数 **1089 == 名册人数 1089**（口径一致）
    · 口令错 → `401`
  临时探针用完即删并复验 404；临时插入的口令用完即清（不动用户已配的凭据）。

════ 八、 关于 CalDAV「本来是好的」这件事 ════
严格说：**服务端实现一直是对的**，缺的是 Apache 那一行 `CGIPassAuth`。
也就是说这个仓库里的 CalDAV 之前**上线即不可用**（只是没人用真实客户端试过）。
本批顺手把它一起修好了 —— 现在 /dav/ 与 /carddav/ 都能被 iOS / DAVx⁵ 正常连上。
This commit is contained in:
laoyang
2026-10-06 17:33:48 +08:00
parent 41572b77e7
commit 6ceae11293
16 changed files with 1292 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
carddav.php
+250
View File
@@ -0,0 +1,250 @@
<?php
/**
* 家书 FamilyBook · CardDAV 入口（v24 第 22 批）
*
* 用户原话：「名册，增加cardav同步功能。」
* 把「我的名册」放进手机通讯录（iOS 通讯录 / DAVx⁵ / Thunderbird / 群晖 Contacts）。
*
* 地址：https://<站点>/carddav/
* 账号：手机号或姓名（同登录）
* 口令：**DAV 通用口令**（在「个人设置 → DAV 同步」生成，不是登录口令）
* ⚠️ 与 CalDAV（/dav/）**共用同一把**（用户 2026-10-06 确认）：
* 手机上填一次，日历本与通讯录一起进来。
*
* ⚠️ 为什么是独立文件、独立前缀（/carddav/ 而不是 /dav/card/）：
* 见 App\CardDav 的类注释 —— 两种资源类型混在一棵树里要靠猜客户端意图，
* 猜错的表现是"连上了但一本都看不到"，比连不上更难查。
* 二者共用的是**鉴权**（Auth::davAuth）与**口令表**（dav_credentials），
* 那才是用户关心的"用用户名和口令来同步"。
*
* ⚠️ 与 dav.php 一样，这里不做"半支持"：写方法一律 403。
* 手机上加/改/删联系人**不会**回写到家书 —— 与其让用户以为同步了，不如明说。
*/
declare(strict_types=1);
require __DIR__ . '/app/bootstrap.php';
use App\Auth;
use App\CardDav;
/** 统一的失败出口（DAV 客户端只认状态码，正文给点人话便于排查） */
function cd_fail(int $code, string $msg): void
{
http_response_code($code);
header('Content-Type: text/plain; charset=utf-8');
echo $msg;
exit;
}
// ---- 1. 鉴权：HTTP Basic（与 CalDAV 同一套 —— 一把口令管两种同步）----
$user = $_SERVER['PHP_AUTH_USER'] ?? null;
$pass = $_SERVER['PHP_AUTH_PW'] ?? null;
// 有些 SAPI 不填 PHP_AUTH_USER，得自己从 Authorization 头里拆
if ($user === null && !empty($_SERVER['HTTP_AUTHORIZATION'])) {
if (preg_match('/^Basic\s+(.+)$/i', (string)$_SERVER['HTTP_AUTHORIZATION'], $m)) {
$decoded = base64_decode($m[1], true);
if ($decoded !== false && strpos($decoded, ':') !== false) {
[$user, $pass] = explode(':', $decoded, 2);
}
}
}
$who = Auth::davAuth($user, $pass);
if (!$who) {
header('WWW-Authenticate: Basic realm="FamilyBook DAV"');
cd_fail(401, '需要 DAV 口令（在「个人设置 → DAV 同步」页生成，不是登录密码）。');
}
$familyId = (int)$who['family_id'];
$me = (int)$who['person_id'];
$method = strtoupper((string)($_SERVER['REQUEST_METHOD'] ?? 'GET'));
$path = (string)parse_url((string)($_SERVER['REQUEST_URI'] ?? '/carddav/'), PHP_URL_PATH);
$hit = CardDav::parsePath($path);
$bookId = (int)$hit['book'];
$cardId = (int)$hit['card'];
// ---- 2. 只读：写方法直接拒（明确拒比"写一半"好）----
// ⚠️ ADDRESSBOOK（老客户端会发这个非标准方法）也一起挡掉：它没有定义，
// 放过去会落到最后的 405，不如在这里给一句明确的"我们只读"。
if (in_array($method, ['PUT', 'DELETE', 'PROPPATCH', 'MKCOL', 'POST', 'PATCH', 'ADDRESSBOOK'], true)) {
cd_fail(403, '家书的通讯录目前是只读同步：请在本站的名册里增删改联系人。');
}
// ---- 3. OPTIONS：客户端第一句就问"你支持什么" ----
if ($method === 'OPTIONS') {
http_response_code(200);
// addressbook 是 CardDAV 的能力声明（RFC 6352 §6.1）；
// 带上 3, extended-mkcol 让个别客户端不再试写方法。
header('DAV: 1, 2, 3, addressbook');
header('Allow: OPTIONS, GET, HEAD, PROPFIND, REPORT');
header('MS-Author-Via: DAV');
exit;
}
// ---- 4. 找不到那一本 → 404（不要回 200 空列表：客户端会以为"这本是空的"）----
if ($bookId > 0 && !in_array($bookId, array_column(CardDav::books($familyId, $me), 'id'), true)) {
cd_fail(404, '没有这本通讯录。');
}
$vcfOfBook = static function (int $bid) use ($familyId, $me): string {
// 家庭场景只有一本，任何合法 id 都回同一份内容 —— 但**必须校验 id 合法**，
// 否则 /carddav/999.vcf/ 也能拉到数据，客户端会记下一个"错的地址"。
return CardDav::vcf($familyId, $me);
};
// ---- 5. PROPFIND：清单 / 属性 / 资源列表 ----
if ($method === 'PROPFIND') {
$depth = (string)($_SERVER['HTTP_DEPTH'] ?? '0');
if ($bookId === 0) {
// 根：列出这个人可见的通讯录
$parts = [];
foreach (CardDav::books($familyId, $me) as $b) {
$parts[] = '<d:response><d:href>' . CardDav::x(CardDav::hrefOf($b)) . '</d:href>'
. '<d:propstat><d:prop>'
. '<d:resourcetype><d:collection/><card:addressbook/></d:resourcetype>'
. '<d:displayname>' . CardDav::x((string)$b['name']) . '</d:displayname>'
. '<card:addressbook-description>'
. CardDav::x((string)$b['description']) . '</card:addressbook-description>'
. '<d:current-user-privilege-set><d:privilege><d:read/></d:privilege></d:current-user-privilege-set>'
. '</d:prop></d:propstat></d:response>';
}
CardDav::multis();
echo '<?xml version="1.0" encoding="utf-8"?>' . "\n"
. '<d:multistatus xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav">'
. implode('', $parts) . '</d:multistatus>';
exit;
}
if ($depth === '1') {
// 某本里的卡片清单：客户端拿这个 ETag 判断"要不要重新拉"
$rows = CardDav::rows($familyId, $me);
$parts = [];
foreach ($rows as $r) {
$rid = (int)($r['id'] ?? 0);
if ($rid <= 0) {
continue;
}
$card = CardDav::cardOf($r);
// ⚠️ 资源名用 **persons.id**（不是 UID）：URL 与正文 UID 可以不同，
// 但用 id 让 href 稳定、且与 CardDav::one 的入参一一对应。
$parts[] = '<d:response><d:href>'
. CardDav::x(CardDav::bookHref($bookId) . $rid . '.vcf') . '</d:href>'
. '<d:propstat><d:prop>'
. '<d:getetag>' . CardDav::x($card['etag']) . '</d:getetag>'
. '<d:resourcetype/>'
. '<d:getcontenttype>text/vcard; charset=utf-8</d:getcontenttype>'
. '<d:getcontentlength>' . strlen($card['body']) . '</d:getcontentlength>'
. '</d:prop></d:propstat></d:response>';
}
CardDav::multis();
echo '<?xml version="1.0" encoding="utf-8"?>' . "\n"
. '<d:multistatus xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav">'
. implode('', $parts) . '</d:multistatus>';
exit;
}
// Depth 0：这本通讯录自身的属性
$book = null;
foreach (CardDav::books($familyId, $me) as $b) {
if ((int)$b['id'] === $bookId) {
$book = $b;
}
}
CardDav::multis();
echo '<?xml version="1.0" encoding="utf-8"?>' . "\n"
. '<d:multistatus xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav">'
. '<d:response><d:href>' . CardDav::x(CardDav::bookHref($bookId)) . '</d:href>'
. '<d:propstat><d:prop>'
. '<d:resourcetype><d:collection/><card:addressbook/></d:resourcetype>'
. '<d:displayname>' . CardDav::x((string)($book['name'] ?? '家庭名册')) . '</d:displayname>'
. '<d:current-user-privilege-set><d:privilege><d:read/></d:privilege></d:current-user-privilege-set>'
. '</d:prop></d:propstat></d:response></d:multistatus>';
exit;
}
// ---- 6. GET / HEAD：整本导出成一个 vcf（不少客户端就走这一条）----
if ($method === 'GET' || $method === 'HEAD') {
if ($bookId === 0) {
cd_fail(404, '没有这本通讯录。');
}
$vcf = $vcfOfBook($bookId);
$etag = CardDav::etag($vcf);
if (trim((string)($_SERVER['HTTP_IF_NONE_MATCH'] ?? '')) === $etag) {
http_response_code(304);
header('ETag: ' . $etag);
exit;
}
http_response_code(200);
// text/vcard（RFC 6352 用这个 MIME；个别老客户端认 text/x-vcard）
header('Content-Type: text/vcard; charset=utf-8');
header('ETag: ' . $etag);
header('Cache-Control: private, max-age=0, must-revalidate');
header('Content-Disposition: inline; filename="familybook.vcf"');
if ($method === 'GET') {
echo $vcf;
}
exit;
}
// ---- 7. REPORT：addressbook-query（按条件） / addressbook-multiget（按 href 取）----
if ($method === 'REPORT') {
if ($bookId === 0) {
cd_fail(404, '没有这本通讯录。');
}
$bodyRaw = (string)file_get_contents('php://input');
// 单张卡请求（/carddav/1.vcf/12.vcf）
if ($cardId > 0) {
$one = CardDav::one($familyId, $me, $cardId);
if (!$one) {
cd_fail(404, '没有这张联系人卡片。');
}
/* ⚠️ 正文与 ETag 都从 cardOf 取（**同一处**算），别在这里另算一次 ——
本轮实测：PROPFIND 用不带结尾 CRLF 的正文算 ETag、这里用带 CRLF 的算，
同一张卡两个 ETag → 客户端认为它一直在变、反复重拉（同步不收敛）。
结尾那条 CRLF 只加在**正文**（address-data 要有完整的 vCard 文本），
不参与 ETag。 */
$card = CardDav::cardOf($one);
CardDav::multis();
echo '<?xml version="1.0" encoding="utf-8"?>' . "\n"
. '<d:multistatus xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav">'
. '<d:response><d:href>'
. CardDav::x(CardDav::bookHref($bookId) . $cardId . '.vcf') . '</d:href>'
. '<d:propstat><d:prop>'
. '<d:getetag>' . CardDav::x($card['etag']) . '</d:getetag>'
. '<card:address-data>' . CardDav::x($card['body'] . "\r\n") . '</card:address-data>'
. '</d:prop></d:propstat></d:response></d:multistatus>';
exit;
}
// ⚠️ multiget 时客户端会点明要哪几张（href 里带 id）。
// 我们**整本给**、由客户端自己按 href 挑 —— 家庭场景一本最多几百张，
// 整本回的体积完全可接受，而"解析客户端要哪些"那套逻辑
// （href 可能是绝对 URL、可能带前缀）是出错率最高的地方，不值得写。
$rows = CardDav::rows($familyId, $me);
$parts = [];
foreach ($rows as $r) {
$rid = (int)($r['id'] ?? 0);
if ($rid <= 0) {
continue;
}
$card = CardDav::cardOf($r);
$parts[] = '<d:response><d:href>'
. CardDav::x(CardDav::bookHref($bookId) . $rid . '.vcf') . '</d:href>'
. '<d:propstat><d:prop>'
. '<d:getetag>' . CardDav::x($card['etag']) . '</d:getetag>'
. '<card:address-data>' . CardDav::x($card['body'] . "\r\n") . '</card:address-data>'
. '</d:prop></d:propstat></d:response>';
}
unset($bodyRaw);
CardDav::multis();
echo '<?xml version="1.0" encoding="utf-8"?>' . "\n"
. '<d:multistatus xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav">'
. implode('', $parts) . '</d:multistatus>';
exit;
}
// ---- 8. 其它方法一律 405（并告知支持哪些）----
header('Allow: OPTIONS, GET, HEAD, PROPFIND, REPORT');
cd_fail(405, '不支持这个请求方法。');