dsh-calendar 0.4.0 → 0.5.0

package/README.en.md

@@ -1,12 +1,14 @@
 # dsh-calendar
 
+![npm](https://img.shields.io/npm/v/dsh-calendar) ![downloads](https://img.shields.io/npm/dm/dsh-calendar) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-calendar) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-calendar?style=social)
+
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-DSH community plugin: read/write calendar events via CalDAV. Provides 5 model-facing tools (calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search), supporting Google / iCloud / Nextcloud and any CalDAV server. This round is a node half-body with no settings-page UI; all configuration goes through the profile's cordis.patch.yml.
+DSH community plugin: read/write calendar events via CalDAV. Provides 5 calendar tools (calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search) plus the offline `calendar_health` configuration check. Google uses OAuth 2.0; iCloud / Nextcloud / custom servers retain Basic authentication by default. No settings-page UI; all configuration goes through the profile's cordis.patch.yml.
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Plugin contracts and Web-profile co-loading verified against the official source-run `@deepseek-ai/dsh@0.1.3-alpha.1` baseline on 2026-09-07. OAuth tests use mocked token and DAV responses, not a real Google account. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 
@@ -31,11 +33,13 @@ All configuration lives in your profile's cordis.patch.yml; override the `calend
 
 - `provider`: google | icloud | nextcloud | custom
 - `caldavUrl`: full calendar collection URL (required for custom / icloud; google / nextcloud can also override the preset manually)
-- `username`: CalDAV account (account email for Google / iCloud)
-- `password`: password; for Google / iCloud use an app-specific password. Recommended to use the `DSH_CALENDAR_PASSWORD` env var to avoid storing it in plaintext.
+- `authMethod`: `basic` | `oauth`; Google defaults to and requires `oauth`, other providers default to `basic`. Opt in explicitly for another OAuth server. Google credentials in the environment never switch a Basic provider to OAuth automatically.
+- `username` / `password`: required only for Basic authentication. Use an app-specific password for iCloud, preferably via `DSH_CALENDAR_PASSWORD`. **Google CalDAV rejects all Basic passwords, including app-specific passwords.**
+- `clientId` / `clientSecret` / `refreshToken`: required for OAuth; also read from `DSH_CALENDAR_CLIENT_ID` / `DSH_CALENDAR_CLIENT_SECRET` / `DSH_CALENDAR_REFRESH_TOKEN`. Non-empty config values take precedence over environment variables. Never commit secrets or tokens to Git.
+- `tokenUrl`: also read from `DSH_CALENDAR_TOKEN_URL`; defaults to `https://oauth2.googleapis.com/token` for Google and is required for other OAuth providers. OAuth tokenUrl and caldavUrl must use HTTPS without embedded credentials, query parameters or fragments.
 - `calendarId`: google-specific, the calendar ID (usually your email)
 - `host` / `user` / `calendar`: nextcloud-specific
-- `proxyUrl`: optional HTTP proxy (e.g. `http://127.0.0.1:7890`); routes only this plugin's CalDAV requests through it
+- `proxyUrl`: optional HTTP proxy (e.g. `http://127.0.0.1:7890`); both OAuth token requests and CalDAV requests use this transport
 
 ### Google example
 
@@ -44,13 +48,25 @@ All configuration lives in your profile's cordis.patch.yml; override the `calend
   name: dsh-calendar
   config:
     provider: google
-    username: you@gmail.com
     calendarId: you@gmail.com
-    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+    # authMethod: oauth  # the default for Google
+    # Provide clientId / clientSecret / refreshToken via environment variables
 ```
 
 Google's CalDAV collection URL is assembled by the plugin: `https://apidata.googleusercontent.com/caldav/v2/<calendarId>/events`.
 
+Set these placeholder values in the same terminal that starts source-run `pnpm dsh` or ordinary `dsh`:
+
+```bash
+export DSH_CALENDAR_CLIENT_ID='your OAuth client ID'
+export DSH_CALENDAR_CLIENT_SECRET='your OAuth client secret'
+export DSH_CALENDAR_REFRESH_TOKEN='your authorized refresh token'
+```
+
+These credentials come from your own Google Cloud OAuth client and a user authorization, not an email app password. Follow the [Google CalDAV setup guide](https://developers.google.com/workspace/calendar/caldav/v2/guide) to enable the API and configure OAuth. Request `https://www.googleapis.com/auth/calendar` for calendar read/write and offline access (`access_type=offline`) to obtain a refresh token; see [Google's offline authorization documentation](https://developers.google.com/identity/protocols/oauth2/web-server#offline). The plugin does not provide a browser login UI or a separate login CLI; supply an already authorized refresh token.
+
+Access tokens are cached in memory and checked before each DAV request, with refresh before expiry. Both token and DAV requests inherit the tool call's AbortSignal. A 401 invalidates the token for the next call; **writes are never replayed automatically**. OAuth requests do not follow redirects or send Bearer tokens to cross-origin object hrefs, so configure the final calendar collection URL. Runtime tokens are not written to configuration or logs. If another OAuth provider rotates refresh tokens, supply valid credentials again when restarting.
+
 ### iCloud example
 
 ```yaml
@@ -93,20 +109,21 @@ The plugin assembles: `https://cloud.example.com/remote.php/dav/calendars/alice/
     # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
 ```
 
-## App-specific password guidance
+## Authentication troubleshooting
 
-Google: sign in to myaccount.google.com → Security → 2-Step Verification (must be enabled first) → App passwords, choose "Other" to generate a 16-character password, and fill it into `password` or `DSH_CALENDAR_PASSWORD`. You cannot use your Google login password.
+Google: OAuth 2.0 only. On 401/403, check OAuth authorization, calendar scope and calendar permissions. On refresh failure, verify clientId/clientSecret/refreshToken and re-authorize if the grant was revoked or expired. **Generating another app password cannot fix Google CalDAV authentication.**
 
 iCloud: sign in to appleid.apple.com → Sign-In and Security → App-Specific Passwords, generate one and fill it into `password` or `DSH_CALENDAR_PASSWORD`. You cannot use your Apple ID password.
 
-If a call returns 401/403, it's usually the wrong password (login password used instead of an app-specific password); the plugin returns a Chinese hint.
+Nextcloud / custom Basic servers: check the account, password or provider-issued app token and calendar permissions. `calendar_health` checks configuration only; it neither connects nor proves authorization. Use `calendar_list` to verify the real connection.
 
 ## Proxy
 
-If your CalDAV server is not directly reachable from your network (some regional or corporate networks block it), set `proxyUrl` in the plugin config, e.g. `http://127.0.0.1:7890`, and restart. The proxy only routes this plugin's CalDAV requests; it does not affect other plugins in the same process.
+If your CalDAV server is not directly reachable from your network (some regional or corporate networks block it), set `proxyUrl` in the plugin config, e.g. `http://127.0.0.1:7890`, and restart. Both token refresh and DAV requests use that HTTP proxy; it does not affect other plugins in the same process.
 
 ## Tool reference
 
+- `calendar_health`: offline provider, endpoint and Basic/OAuth credential-completeness checks; never displays secrets or connects to the server.
 - `calendar_list`: list events in a time range (start/end, ISO 8601; defaults to the next 7 days). Recurring events are expanded by default (`expand` defaults to true, `maxOccurrences` defaults to 30, clamped to 1-200): each occurrence is a separate row with `isOccurrence: true` and `seriesStart`; non-recurring events keep `isOccurrence: false`. With `expand=false`, recurring events are returned as a single original entry with `rrule`. Results are stably sorted by start time.
 - `calendar_create`: create an event (summary/start/end required; description/location/allDay/rrule optional). Validates real calendar dates and `end >= start`.
 - `calendar_update`: edit an event by uid (summary/start/end/description/location/allDay/rrule optional; omitted fields keep their original values, including the recurrence rule).
@@ -120,22 +137,25 @@ The stable event identifier `uid` is the CalDAV href (full object URL); `calenda
 Input and output are uniformly ISO 8601. Timed events are output in UTC (e.g. `2025-01-15T01:00:00Z`); all-day events output `YYYY-MM-DD`. Input may carry a timezone offset (e.g. `2025-01-15T09:00:00+08:00`); the plugin converts to UTC internally for storage.
 
 
-## v0.3.2 improvements
+## Changelog
 
-- Fix `calendar_update` dropping `rrule` while updating other fields.
-- Validate `end >= start` and reject impossible dates such as `2025-02-30`.
-- Sort `calendar_list` / `calendar_search` output by start time and clamp search `limit` to 1-200.
-- Reset the cached CalDAV client after creation failure so the next tool call can retry.
+- **0.5.0 (2026-09-07)**: fix Google CalDAV #2 with OAuth configuration/environment credentials, request-time refresh, cancellation and proxy forwarding. Make health checks and error guidance authentication-aware; retain Basic authentication for other servers.
+- **0.4.0**: new `calendar_health` self-check (offline endpoint and credential configuration checks, not a connection test).
+- **0.3.2**:
+  - Fix `calendar_update` dropping `rrule` while updating other fields.
+  - Validate `end >= start` and reject impossible dates such as `2025-02-30`.
+  - Sort `calendar_list` / `calendar_search` output by start time and clamp search `limit` to 1-200.
+  - Reset the cached CalDAV client after creation failure so the next tool call can retry.
 
 ## Known limitations
 
 - Recurring event expansion: calendar_list expands RRULE by default via ICAL.RecurExpansion (`expand=true`), capped by `maxOccurrences`; calendar_search still returns the original series (not expanded).
 - No single-instance edit/delete: calendar_update / calendar_delete operate on the whole recurring series (by uid); you cannot modify or delete just one occurrence (no RECURRENCE-ID instance-level operations).
-- No OAuth: Basic auth only (app-specific password); Google / iCloud OAuth login flows are not supported.
+- OAuth credentials must be obtained beforehand: refresh-token authentication is supported, but there is no browser login UI / login CLI and runtime tokens are not written back to configuration.
 - Timezone rules: events with TZID (named timezone) are output converted to UTC (Z); all-day boundaries, DST, and other complex timezone rules are not handled finely.
 - No settings-page UI: this round is a node half-body; config only via cordis.patch.yml, no Web settings page.
 - Calendar discovery: iCloud requires manually filling the full calendar collection URL; no principal auto-discovery or multi-calendar selection.
-- Cancellation/timeout: tools rely on `timeoutMs` (60 seconds) for overall timeout; AbortSignal is not propagated to individual network requests.
+- Cancellation/timeout: tools use `timeoutMs` (60 seconds) and forward the host AbortSignal into token refresh and DAV network requests. Concurrent calls cancel independently.
 
 ## Development
 
@@ -144,4 +164,4 @@ pnpm install
 pnpm test   # 构建 + node --test
 ```
 
-Build output in `lib/`; tests in `test/*.test.mjs` (no real account needed).
+Build output in `lib/`; tests in `test/*.test.mjs` (no real account needed).

package/README.md

@@ -9,11 +9,11 @@
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 
-DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个面向模型的工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search），支持 Google / iCloud / Nextcloud 及任意 CalDAV 服务器。本轮为 node 半身，不含设置页 UI，配置全部走 profile 的 cordis.patch.yml。
+DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个日历操作工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search）和 `calendar_health` 配置自检。Google 使用 OAuth 2.0；iCloud / Nextcloud / 自定义服务器默认保留 Basic 认证。不含设置页 UI，配置全部走 profile 的 cordis.patch.yml。
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+已在 `@deepseek-ai/dsh@0.1.3-alpha.1` 官方源码基线上验证插件接口与 Web profile 同载（2026-09-07）。OAuth 使用离线模拟的令牌端点和 DAV 响应测试，未使用真实 Google 账号验证。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -29,9 +29,11 @@ dsh plugin --profile web add dsh-calendar
 
 - `provider`：google | icloud | nextcloud | custom
 - `caldavUrl`：完整日历集合 URL（custom / icloud 必填；google / nextcloud 也可手填覆盖预设）
-- `username`：CalDAV 账号（Google / iCloud 为账号邮箱）
-- `password`：密码；Google / iCloud 请用应用专用密码。推荐用环境变量 `DSH_CALENDAR_PASSWORD`，避免明文入库。
-- `proxyUrl`：本机代理地址（如 http://127.0.0.1:7890）。中国大陆访问 Google / iCloud 必填，详见上文「特殊代理配置」专节；国内可直连的 CalDAV 服务无需填写。
+- `authMethod`：`basic` | `oauth`；Google 默认且必须为 `oauth`，其他 provider 默认 `basic`。其他 OAuth 服务器需显式设置 `oauth`，不会因环境中存在 Google 凭据而自动切换。
+- `username` / `password`：仅 Basic 认证必需。iCloud 请用应用专用密码；密码推荐用环境变量 `DSH_CALENDAR_PASSWORD`。**Google CalDAV 不接受任何 Basic 密码，包括应用专用密码。**
+- `clientId` / `clientSecret` / `refreshToken`：OAuth 必需；分别支持 `DSH_CALENDAR_CLIENT_ID` / `DSH_CALENDAR_CLIENT_SECRET` / `DSH_CALENDAR_REFRESH_TOKEN`。非空配置值优先于环境变量。请勿把密钥或令牌提交到 Git。
+- `tokenUrl`：可用 `DSH_CALENDAR_TOKEN_URL`；Google 默认 `https://oauth2.googleapis.com/token`，其他 OAuth 服务必填。OAuth 的 tokenUrl 与 caldavUrl 必须为不含内嵌账号密码、查询参数或片段的 HTTPS 地址。
+- `proxyUrl`：可选 HTTP 代理地址（如 http://127.0.0.1:7890）；令牌刷新和 CalDAV 请求共用该代理。可直连时无需填写。
 - `calendarId`：google 专用，日历 ID（通常是你的邮箱）
 - `host` / `user` / `calendar`：nextcloud 专用
 
@@ -46,15 +48,14 @@ dsh plugin --profile web remove dsh-calendar
 
 ## 中国用户：特殊代理配置（Google / iCloud）
 
-Google 与 iCloud 的 CalDAV 端点在中国大陆**不可直连**，需要配合你常用的梯子/特殊代理使用。插件内置 `proxyUrl` 配置：把 CalDAV 请求路由到**你本机代理客户端的端口**，不影响其他插件，也无需改任何系统设置。
+若本机网络无法直连 Google / iCloud，插件内置的 `proxyUrl` 可把 OAuth 令牌请求和 CalDAV 请求路由到**你本机 HTTP 代理客户端的端口**，不影响其他插件，也无需改任何系统设置。
 
 ```yaml
 - id: calendar
   config:
     provider: google
-    username: you@gmail.com
     calendarId: you@gmail.com
-    password: 你的应用专用密码
+    # OAuth 凭据通过下文三个环境变量提供
     proxyUrl: http://127.0.0.1:7890   # 改成你代理客户端的本地端口
 ```
 
@@ -75,13 +76,25 @@ Google 与 iCloud 的 CalDAV 端点在中国大陆**不可直连**，需要配
   name: dsh-calendar
   config:
     provider: google
-    username: you@gmail.com
     calendarId: you@gmail.com
-    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+    # authMethod: oauth  # Google 默认即为 oauth
+    # clientId / clientSecret / refreshToken 推荐用环境变量
 ```
 
 Google 的 CalDAV 集合 URL 由插件拼成：`https://apidata.googleusercontent.com/caldav/v2/<calendarId>/events`。
 
+在启动源码版 `pnpm dsh` 或普通 `dsh` 的同一个终端中设置（以下均为占位值）：
+
+```bash
+export DSH_CALENDAR_CLIENT_ID='你的 OAuth 客户端 ID'
+export DSH_CALENDAR_CLIENT_SECRET='你的 OAuth 客户端密钥'
+export DSH_CALENDAR_REFRESH_TOKEN='你授权后取得的 refresh token'
+```
+
+凭据必须来自你自己的 Google Cloud OAuth 客户端和一次用户授权，而不是邮箱应用专用密码。按 [Google CalDAV 官方设置说明](https://developers.google.com/workspace/calendar/caldav/v2/guide) 启用 API、配置 OAuth；申请日历读写范围 `https://www.googleapis.com/auth/calendar`，并请求离线访问（`access_type=offline`）以取得刷新令牌，参见 [Google 离线授权说明](https://developers.google.com/identity/protocols/oauth2/web-server#offline)。尚未提供浏览器一键登录或独立登录 CLI；已有 OAuth 配置的用户可直接填入刷新令牌。
+
+插件在内存中缓存访问令牌，并在每次 DAV 请求前检查有效期、提前刷新；令牌请求与 DAV 请求都会透传调用的取消信号。401 会使缓存失效，下一次调用重新刷新，**不会自动重放写请求**。OAuth 请求不跟随重定向、不向其它源的对象 href 发送 Bearer token，请填写最终日历集合地址。运行时令牌不会写入配置或日志；若其他 OAuth 提供方轮换 refresh token，重启时需要重新提供有效凭据。
+
 ### iCloud 示例
 
 ```yaml
@@ -124,16 +137,17 @@ iCloud 需要完整日历集合 URL（含你的用户 ID 与日历 ID），在 i
     # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
 ```
 
-## 应用专用密码指引
+## 认证失败排查
 
-Google：登录 myaccount.google.com → 安全 → 两步验证（需先开启）→ 应用专用密码，选择「其他」生成 16 位密码，填到 `password` 或 `DSH_CALENDAR_PASSWORD`。不能用你的 Google 登录密码。
+Google：仅支持 OAuth 2.0。401/403 时检查 OAuth 授权、日历范围与日历访问权限；令牌刷新失败时核对 clientId/clientSecret/refreshToken，授权被撤销或过期时重新授权。**重新生成应用专用密码不能解决 Google CalDAV 认证失败。**
 
 iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生成后填到 `password` 或 `DSH_CALENDAR_PASSWORD`。不能用你的 Apple ID 密码。
 
-若调用报 401/403，多半是密码不对（用了登录密码而非应用专用密码），插件会返回中文提示。
+Nextcloud / 自定义 Basic 服务：检查账号、密码或服务要求的应用令牌及日历权限。`calendar_health` 只检查配置完整性，不联网、不证明授权成功；请再用 `calendar_list` 验证真实连接。
 
 ## 工具清单
 
+- `calendar_health`：离线检查服务商、日历集合地址与 Basic/OAuth 凭据完整性，不回显密钥、不发起网络连接。
 - `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）。默认展开重复事件（`expand` 默认 true，`maxOccurrences` 默认 30、clamp 1-200）：每个实例独立成行，带 `isOccurrence: true` 与 `seriesStart`；非重复事件保持 `isOccurrence: false`。`expand=false` 时重复事件按原始单条返回并带 `rrule`。结果按开始时间稳定排序
 - `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay/rrule 可选）。严格校验真实日历日期与 `end >= start`
 - `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay/rrule 可选，未提供保留原值，重复规则不再丢失）
@@ -146,26 +160,29 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 输入输出统一 ISO 8601。定时事件输出为 UTC（如 `2025-01-15T01:00:00Z`），全天事件输出 `YYYY-MM-DD`。输入可带时区偏移（如 `2025-01-15T09:00:00+08:00`），插件内部转 UTC 存储。
 
-## v0.3.2 优化
+## 版本记录
 
-- 修复 `calendar_update` 更新其他字段时丢失 `rrule` 的问题。
-- 更新与新建都会校验 `end >= start`，并拒绝 `2025-02-30` 这类不存在的日期。
-- `calendar_list` / `calendar_search` 输出按开始时间稳定排序；搜索 `limit` clamp 到 1-200。
-- CalDAV 客户端创建失败后清空缓存，下一次调用可自动重试，不再永久复用 rejected promise。
+- **0.5.0（2026-09-07）**：修复 Google CalDAV #2：新增 OAuth 凭据与环境变量配置、请求时刷新、取消与代理透传；健康检查区分 Basic/OAuth，修正误导的应用专用密码说明。保留其他服务的 Basic 认证。
+- **0.4.0**：新增 `calendar_health` 自检（离线检查 CalDAV 端点与凭据配置，不验证连接）。
+- **0.3.2**：
+  - 修复 `calendar_update` 更新其他字段时丢失 `rrule` 的问题。
+  - 更新与新建都会校验 `end >= start`，并拒绝 `2025-02-30` 这类不存在的日期。
+  - `calendar_list` / `calendar_search` 输出按开始时间稳定排序；搜索 `limit` clamp 到 1-200。
+  - CalDAV 客户端创建失败后清空缓存，下一次调用可自动重试，不再永久复用 rejected promise。
 
 
 ## 已知限制
 
-- **国内网络**：Google 与 iCloud 的 CalDAV 端点在中国大陆不可直连；可用 `proxyUrl` 走本机梯子/特殊代理，或改用国内可直连的 CalDAV 端点（自建 Nextcloud/Radicale）。
+- **网络可达性**：若无法直连，可用 `proxyUrl` 指定本机 HTTP 代理，或改用可直连的 CalDAV 端点。
 
 
 - 重复事件展开：calendar_list 默认用 ICAL.RecurExpansion 展开 RRULE（`expand=true`），受 `maxOccurrences` 封顶；calendar_search 仍返回原始系列（不展开）。
 - 不支持单次实例的改/删：calendar_update / calendar_delete 针对整个重复系列（按 uid 操作），无法只修改或删除某一次发生（不支持 RECURRENCE-ID 实例级操作）。
-- 不做 OAuth：仅支持 Basic 认证（应用专用密码），不支持 Google / iCloud 的 OAuth 登录流程。
+- OAuth 凭据需要事先取得：支持刷新令牌认证，但不提供浏览器登录 UI / 登录 CLI，也不把运行时令牌写回配置文件。
 - 时区规则：带 TZID（命名时区）的事件输出会转成 UTC（Z）；全天边界、夏令时等复杂时区规则不做精细化处理。
 - 无设置页 UI：本轮为 node 半身，配置只走 cordis.patch.yml，不提供 Web 设置页。
 - 日历发现：iCloud 需手动填完整日历集合 URL；不做 principal 自动发现与多日历选择。
-- 取消/超时：工具依赖 timeoutMs（60 秒）做整体超时，不在单次网络请求上透传 AbortSignal。
+- 取消/超时：工具使用 timeoutMs（60 秒），并向令牌刷新与 DAV 网络请求透传宿主 AbortSignal；并发调用独立取消。
 
 ## 开发
 
@@ -180,4 +197,4 @@ pnpm test   # 构建 + node --test
 
 - [dsh-calendar](https://github.com/STARDUSTLC666/dsh-calendar) — CalDAV 日历五件套
 - [dsh-slack](https://github.com/STARDUSTLC666/dsh-slack) — Slack 通知/收件箱
-- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）
+- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）

package/cordis.patch.yml

@@ -8,9 +8,13 @@
 #     name: 'dsh-calendar'
 #     config:
 #       provider: google              # google | icloud | nextcloud | custom
-#       username: you@gmail.com       # CalDAV 账号（Google/iCloud 用账号邮箱）
 #       calendarId: you@gmail.com     # google：日历 ID（通常是你的邮箱地址）
-#       # password: xxxx              # 应用专用密码；推荐改用环境变量 DSH_CALENDAR_PASSWORD
+#       # authMethod: oauth           # google 默认 oauth，不接受 Basic/应用专用密码
+#       # clientId: ...               # 或 DSH_CALENDAR_CLIENT_ID
+#       # clientSecret: ...           # 推荐用环境变量 DSH_CALENDAR_CLIENT_SECRET
+#       # refreshToken: ...           # 推荐用环境变量 DSH_CALENDAR_REFRESH_TOKEN
+#       # proxyUrl: http://127.0.0.1:7890  # 若需要，令牌刷新与 CalDAV 共用此代理
+#       # iCloud/Nextcloud/custom 默认 Basic：配置 username 与 DSH_CALENDAR_PASSWORD
 #
 - insert:
     - id: calendar

package/lib/caldav.d.ts

@@ -23,20 +23,20 @@ export declare class CalendarService {
     list(startIso: string, endIso: string, options?: {
         expand?: boolean;
         maxOccurrences?: number;
-    }): Promise<CalendarEvent[]>;
+    }, signal?: AbortSignal): Promise<CalendarEvent[]>;
     /** 列出全部事件（客户端过滤用）。 */
-    all(): Promise<CalendarEvent[]>;
+    all(signal?: AbortSignal): Promise<CalendarEvent[]>;
     private toEvents;
     /** 列出并展开：每个对象经 expandEventFromICal 展开为若干实例行。 */
     private toExpandedEvents;
     /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
     private findObject;
     /** 新建事件，返回带 href/uid 的事件。 */
-    create(fields: EventFields): Promise<CalendarEvent>;
+    create(fields: EventFields, signal?: AbortSignal): Promise<CalendarEvent>;
     /** 按 uid 更新事件；未提供的字段保留原值。 */
-    update(uid: string, changes: Partial<EventFields>): Promise<CalendarEvent>;
+    update(uid: string, changes: Partial<EventFields>, signal?: AbortSignal): Promise<CalendarEvent>;
     /** 按 uid 删除事件。 */
-    delete(uid: string): Promise<{
+    delete(uid: string, signal?: AbortSignal): Promise<{
         uid: string;
         href: string;
     }>;

package/lib/caldav.js

@@ -6,6 +6,7 @@
  */
 import { createDAVClient } from 'tsdav';
 import { createProxyFetch } from './proxy-fetch.js';
+import { createOAuthFetch, OAuthError } from './oauth.js';
 import { buildICalString, expandEventFromICal, generateUid, parseEventFromICal, } from './ical.js';
 /** CalDAV 操作错误：带中文指引。 */
 export class CalDAVError extends Error {
@@ -23,14 +24,25 @@ function normalizeUrl(value) {
     const trimmed = value.trim();
     return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
 }
-/** 把底层错误翻译成中文指引；识别 401/403 提示应用专用密码。 */
-function translateError(error, action) {
+function authenticationError(config, status) {
+    const guidance = config.oauth !== undefined
+        ? '请检查 OAuth 授权范围、日历访问权限及 refreshToken；授权失效时请重新授权。Google CalDAV 不接受应用专用密码。'
+        : '请检查 username 与 password / DSH_CALENDAR_PASSWORD；iCloud 必须使用应用专用密码，其他服务请确认账号权限。Google CalDAV 需改用 OAuth 2.0。';
+    return new CalDAVError('账号认证失败（' + status + '）：' + guidance, status);
+}
+/** 把底层错误翻译成与当前认证方式匹配的指引。 */
+function translateError(error, action, config) {
+    if (error instanceof CalDAVError)
+        return error;
+    if (error instanceof OAuthError)
+        return new CalDAVError(error.message, error.status);
     const message = error instanceof Error ? error.message : String(error);
     const status = error?.status;
     if (status === 401 || status === 403 || /401|403/.test(message)) {
-        return new CalDAVError('账号认证失败（401/403）：请检查应用专用密码是否正确生成——' +
-            'Google 需在账号安全里创建「应用专用密码」，iCloud 需在 appleid.apple.com 创建 app 专用密码，' +
-            '不能用登录密码。请在 profile 的 cordis.patch.yml 覆盖 calendar 行或设置环境变量 DSH_CALENDAR_PASSWORD 后重启。', status ?? (/401/.test(message) ? 401 : 403));
+        return authenticationError(config, status ?? (/401/.test(message) ? 401 : 403));
+    }
+    if (config.oauth !== undefined) {
+        return new CalDAVError(action + ' 失败：CalDAV 响应或网络请求异常，请检查日历地址与服务权限。', status);
     }
     return new CalDAVError(action + ' 失败：' + message, status);
 }
@@ -45,11 +57,15 @@ export class CalendarService {
     }
     client() {
         if (this.clientPromise === undefined) {
+            const transport = this.config.proxyUrl !== '' ? createProxyFetch(this.config.proxyUrl) : globalThis.fetch;
+            const oauth = this.config.oauth;
             this.clientPromise = createDAVClient({
                 serverUrl: this.config.caldavUrl,
-                credentials: { username: this.config.username, password: this.config.password },
-                authMethod: 'Basic',
-                ...(this.config.proxyUrl !== '' ? { fetch: createProxyFetch(this.config.proxyUrl) } : {}),
+                credentials: oauth === undefined ? { username: this.config.username, password: this.config.password } : {},
+                // createDAVClient 的 Oauth 分支只在初始化时取头；改由 fetch 在每次请求时检查过期。
+                authMethod: oauth === undefined ? 'Basic' : 'Custom',
+                ...(oauth === undefined ? {} : { authFunction: async () => ({}) }),
+                fetch: oauth === undefined ? transport : createOAuthFetch(oauth, transport, this.config.caldavUrl),
             });
         }
         // 创建失败时清掉缓存，让下一次工具调用有机会重试，而不是永久复用 rejected promise。
@@ -62,36 +78,46 @@ export class CalendarService {
         return { url: this.collectionUrl };
     }
     /** 列出某时间段内的事件；expand 为 true 时在窗口内展开 RRULE。 */
-    async list(startIso, endIso, options) {
+    async list(startIso, endIso, options, signal) {
         const expand = options?.expand !== false;
         const maxOccurrences = options?.maxOccurrences ?? 30;
+        signal?.throwIfAborted();
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const objects = await client.fetchCalendarObjects({
                 calendar: this.calendar(),
                 timeRange: { start: startIso, end: endIso },
                 urlFilter: (url) => typeof url === 'string' && url.length > 0,
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
+            signal?.throwIfAborted();
             return expand
                 ? this.toExpandedEvents(objects, startIso, endIso, maxOccurrences)
                 : this.toEvents(objects);
         }
         catch (error) {
-            throw translateError(error, '读取日历');
+            signal?.throwIfAborted();
+            throw translateError(error, '读取日历', this.config);
         }
     }
     /** 列出全部事件（客户端过滤用）。 */
-    async all() {
+    async all(signal) {
+        signal?.throwIfAborted();
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const objects = await client.fetchCalendarObjects({
                 calendar: this.calendar(),
                 urlFilter: (url) => typeof url === 'string' && url.length > 0,
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
+            signal?.throwIfAborted();
             return this.toEvents(objects);
         }
         catch (error) {
-            throw translateError(error, '读取日历');
+            signal?.throwIfAborted();
+            throw translateError(error, '读取日历', this.config);
         }
     }
     toEvents(objects) {
@@ -112,32 +138,42 @@ export class CalendarService {
         return events;
     }
     /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
-    async findObject(uid) {
+    async findObject(uid, signal) {
+        signal?.throwIfAborted();
         const client = await this.client();
+        signal?.throwIfAborted();
         const target = normalizeUrl(uid);
         const objects = await client.fetchCalendarObjects({
             calendar: this.calendar(),
             urlFilter: (url) => normalizeUrl(url) === target,
+            ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
         });
+        signal?.throwIfAborted();
         return objects.find((object) => normalizeUrl(object.url) === target);
     }
     /** 新建事件，返回带 href/uid 的事件。 */
-    async create(fields) {
-        const iCalString = buildICalString(fields);
-        const filename = (fields.icalUid ?? generateUid()) + '.ics';
+    async create(fields, signal) {
+        signal?.throwIfAborted();
+        const icalUid = fields.icalUid ?? generateUid();
+        const iCalString = buildICalString({ ...fields, icalUid });
+        const filename = icalUid + '.ics';
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const response = await client.createCalendarObject({
                 calendar: this.calendar(),
                 iCalString,
                 filename,
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
-            assertOk(response, '新建事件');
+            signal?.throwIfAborted();
+            assertOk(response, '新建事件', this.config);
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (error instanceof CalDAVError)
                 throw error;
-            throw translateError(error, '新建事件');
+            throw translateError(error, '新建事件', this.config);
         }
         const href = new URL(filename, this.collectionUrl).href;
         const event = parseEventFromICal(iCalString, href);
@@ -146,13 +182,15 @@ export class CalendarService {
         return event;
     }
     /** 按 uid 更新事件；未提供的字段保留原值。 */
-    async update(uid, changes) {
+    async update(uid, changes, signal) {
+        signal?.throwIfAborted();
         let object;
         try {
-            object = await this.findObject(uid);
+            object = await this.findObject(uid, signal);
         }
         catch (error) {
-            throw translateError(error, '查找事件');
+            signal?.throwIfAborted();
+            throw translateError(error, '查找事件', this.config);
         }
         if (object === undefined) {
             throw new CalDAVError('找不到 uid 对应的事件：请用 calendar_list 或 calendar_search 重新获取最新 uid，' +
@@ -182,15 +220,19 @@ export class CalendarService {
         const iCalString = buildICalString(merged);
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const response = await client.updateCalendarObject({
                 calendarObject: { url: object.url, etag: object.etag, data: iCalString },
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
-            assertOk(response, '更新事件');
+            signal?.throwIfAborted();
+            assertOk(response, '更新事件', this.config);
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (error instanceof CalDAVError)
                 throw error;
-            throw translateError(error, '更新事件');
+            throw translateError(error, '更新事件', this.config);
         }
         const event = parseEventFromICal(iCalString, object.url, object.etag);
         if (event === null)
@@ -198,13 +240,15 @@ export class CalendarService {
         return event;
     }
     /** 按 uid 删除事件。 */
-    async delete(uid) {
+    async delete(uid, signal) {
+        signal?.throwIfAborted();
         let object;
         try {
-            object = await this.findObject(uid);
+            object = await this.findObject(uid, signal);
         }
         catch (error) {
-            throw translateError(error, '查找事件');
+            signal?.throwIfAborted();
+            throw translateError(error, '查找事件', this.config);
         }
         if (object === undefined) {
             throw new CalDAVError('找不到 uid 对应的事件：请用 calendar_list 或 calendar_search 重新获取最新 uid，' +
@@ -212,27 +256,30 @@ export class CalendarService {
         }
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const response = await client.deleteCalendarObject({
                 calendarObject: { url: object.url, etag: object.etag },
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
-            assertOk(response, '删除事件');
+            signal?.throwIfAborted();
+            assertOk(response, '删除事件', this.config);
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (error instanceof CalDAVError)
                 throw error;
-            throw translateError(error, '删除事件');
+            throw translateError(error, '删除事件', this.config);
         }
         return { uid: object.url, href: object.url };
     }
 }
 /** 校验 HTTP 响应，把 401/403 与其它非 2xx 转成中文错误。 */
-function assertOk(response, action) {
+function assertOk(response, action, config) {
     if (response.status === 401 || response.status === 403) {
-        throw new CalDAVError('账号认证失败（' + response.status + '）：请检查应用专用密码是否正确生成——' +
-            'Google 需在账号安全里创建「应用专用密码」，iCloud 需在 appleid.apple.com 创建 app 专用密码，' +
-            '不能用登录密码。请在 profile 的 cordis.patch.yml 覆盖 calendar 行或设置环境变量 DSH_CALENDAR_PASSWORD 后重启。', response.status);
+        throw authenticationError(config, response.status);
     }
     if (!response.ok) {
-        throw new CalDAVError(action + ' 失败：服务器返回 ' + response.status + ' ' + response.statusText, response.status);
+        throw new CalDAVError(action + ' 失败：服务器返回 ' + response.status +
+            (config.oauth === undefined ? ' ' + response.statusText : ''), response.status);
     }
 }

package/lib/config.d.ts

@@ -6,16 +6,34 @@
  */
 /** 支持的 provider 预设。 */
 export type CalendarProvider = 'google' | 'icloud' | 'nextcloud' | 'custom';
+export type CalendarAuthMethod = 'basic' | 'oauth';
+/** 长期 OAuth 凭据；短期 access token 只保留在运行时内存中。 */
+export interface CalendarOAuthCredentials {
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}
 /** 插件配置：可在 profile 的 cordis.patch.yml 覆盖 calendar 行的整个 config。 */
 export interface CalendarConfig {
     /** provider 预设；默认 custom。 */
     provider?: CalendarProvider;
     /** 完整日历集合 URL；custom / icloud 必填，google / nextcloud 可由此手填覆盖预设。 */
     caldavUrl?: string;
-    /** CalDAV 账号（Google / iCloud 用账号邮箱）。 */
+    /** Basic 认证账号；OAuth 不要求此字段。 */
     username?: string;
-    /** 密码；支持环境变量 DSH_CALENDAR_PASSWORD。Google / iCloud 请用应用专用密码。 */
+    /** Basic 密码；支持 DSH_CALENDAR_PASSWORD。iCloud 请用应用专用密码；Google 不支持 Basic。 */
     password?: string;
+    /** google 默认 oauth，其他 provider 默认 basic；Google 不允许 basic。 */
+    authMethod?: CalendarAuthMethod;
+    /** OAuth 客户端 ID；也可用 DSH_CALENDAR_CLIENT_ID。 */
+    clientId?: string;
+    /** OAuth 客户端密钥；推荐用 DSH_CALENDAR_CLIENT_SECRET。 */
+    clientSecret?: string;
+    /** OAuth 离线授权的刷新令牌；推荐用 DSH_CALENDAR_REFRESH_TOKEN。 */
+    refreshToken?: string;
+    /** OAuth 令牌端点；Google 自动使用官方端点，其他 provider 的 OAuth 必填。 */
+    tokenUrl?: string;
     /** google：日历 ID（通常是你的邮箱地址）。 */
     calendarId?: string;
     /** nextcloud：主机，如 https://cloud.example.com。 */
@@ -37,21 +55,30 @@ export interface ResolvedConfig {
     caldavUrl: string;
     username: string;
     password: string;
+    oauth?: CalendarOAuthCredentials;
     proxyUrl: string;
 }
 /** 预设端点常量。 */
 export declare const GOOGLE_CALDAV_PREFIX = "https://apidata.googleusercontent.com/caldav/v2/";
+export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
 export declare const ICLOUD_CALDAV_URL = "https://caldav.icloud.com";
 export declare const NEXTCLOUD_PATH = "/remote.php/dav/calendars/";
 /** 配置错误：带中文指引，模型和用户都能读。 */
 export declare class ConfigError extends Error {
     constructor(message: string);
 }
+export declare const CALENDAR_PROVIDERS: readonly CalendarProvider[];
 /**
  * 解析配置为可用的 caldavUrl + 凭证。配置缺失抛出 ConfigError（中文指引）。
  * @param config - 插件 config（可能 undefined）。
  * @param env - 环境变量来源（测试可注入）。
  */
 export declare function resolveConfig(config: CalendarConfig | undefined, env?: NodeJS.ProcessEnv): ResolvedConfig;
+/** Google 必须使用 OAuth；其他 provider 不会被环境中的 Google 凭据切换认证方式。 */
+export declare function resolveAuthMethod(config: CalendarConfig | undefined): CalendarAuthMethod;
+/** OAuth 凭据与 Bearer token 仅允许发往无 URL 内嵌凭据的 HTTPS 端点。 */
+export declare function validateOAuthUrl(value: string, field: string): void;
+/** 独立解析认证，供离线健康检查复用；不会发起网络请求或回显凭据。 */
+export declare function resolveCredentials(config: CalendarConfig | undefined, env?: NodeJS.ProcessEnv): Pick<ResolvedConfig, 'username' | 'password' | 'oauth'>;
 /** 依据 provider 预设或手填字段拼出日历集合 URL。 */
 export declare function buildCaldavUrl(config: CalendarConfig, provider: CalendarProvider): string;

package/lib/config.js

@@ -6,6 +6,7 @@
  */
 /** 预设端点常量。 */
 export const GOOGLE_CALDAV_PREFIX = 'https://apidata.googleusercontent.com/caldav/v2/';
+export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
 export const ICLOUD_CALDAV_URL = 'https://caldav.icloud.com';
 export const NEXTCLOUD_PATH = '/remote.php/dav/calendars/';
 /** 配置错误：带中文指引，模型和用户都能读。 */
@@ -15,7 +16,7 @@ export class ConfigError extends Error {
         this.name = 'ConfigError';
     }
 }
-const PROVIDERS = ['google', 'icloud', 'nextcloud', 'custom'];
+export const CALENDAR_PROVIDERS = ['google', 'icloud', 'nextcloud', 'custom'];
 function nonEmpty(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
@@ -25,7 +26,7 @@ function trimTrailingSlash(value) {
 function normalizeProvider(value) {
     if (value === undefined || value === null || value === '')
         return 'custom';
-    if (typeof value === 'string' && PROVIDERS.includes(value)) {
+    if (typeof value === 'string' && CALENDAR_PROVIDERS.includes(value)) {
         return value;
     }
     throw new ConfigError('dsh-calendar 的 provider 取值不合法：只支持 google / icloud / nextcloud / custom。' +
@@ -38,18 +39,68 @@ function normalizeProvider(value) {
  */
 export function resolveConfig(config, env = process.env) {
     const provider = normalizeProvider(config?.provider);
+    const credentials = resolveCredentials(config, env);
+    const caldavUrl = buildCaldavUrl(config ?? {}, provider);
+    if (credentials.oauth !== undefined)
+        validateOAuthUrl(caldavUrl, 'caldavUrl');
+    return { provider, caldavUrl, ...credentials, proxyUrl: nonEmpty(config?.proxyUrl) ?? '' };
+}
+/** Google 必须使用 OAuth；其他 provider 不会被环境中的 Google 凭据切换认证方式。 */
+export function resolveAuthMethod(config) {
+    const provider = normalizeProvider(config?.provider);
+    const method = config?.authMethod ?? (provider === 'google' ? 'oauth' : 'basic');
+    if (method !== 'basic' && method !== 'oauth') {
+        throw new ConfigError('dsh-calendar 的 authMethod 只支持 basic / oauth。');
+    }
+    if (provider === 'google' && method !== 'oauth') {
+        throw new ConfigError('Google CalDAV 仅支持 OAuth 2.0，不接受 Basic 或应用专用密码；请配置 clientId、clientSecret、refreshToken。');
+    }
+    return method;
+}
+/** OAuth 凭据与 Bearer token 仅允许发往无 URL 内嵌凭据的 HTTPS 端点。 */
+export function validateOAuthUrl(value, field) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === 'https:' && url.username === '' && url.password === '' && url.search === '' && url.hash === '')
+            return;
+    }
+    catch {
+        // 不回显 URL，避免错误配置把凭据带入日志。
+    }
+    throw new ConfigError('dsh-calendar 的 OAuth ' + field + ' 必须是有效的 HTTPS 地址，且不能包含账号、密码、查询参数或片段。');
+}
+/** 独立解析认证，供离线健康检查复用；不会发起网络请求或回显凭据。 */
+export function resolveCredentials(config, env = process.env) {
+    if (resolveAuthMethod(config) === 'oauth') {
+        const clientId = nonEmpty(config?.clientId) ?? nonEmpty(env.DSH_CALENDAR_CLIENT_ID);
+        const clientSecret = nonEmpty(config?.clientSecret) ?? nonEmpty(env.DSH_CALENDAR_CLIENT_SECRET);
+        const refreshToken = nonEmpty(config?.refreshToken) ?? nonEmpty(env.DSH_CALENDAR_REFRESH_TOKEN);
+        const tokenUrl = nonEmpty(config?.tokenUrl) ?? nonEmpty(env.DSH_CALENDAR_TOKEN_URL)
+            ?? (config?.provider === 'google' ? GOOGLE_TOKEN_URL : undefined);
+        const missing = [
+            [clientId, 'clientId / DSH_CALENDAR_CLIENT_ID'],
+            [clientSecret, 'clientSecret / DSH_CALENDAR_CLIENT_SECRET'],
+            [refreshToken, 'refreshToken / DSH_CALENDAR_REFRESH_TOKEN'],
+            [tokenUrl, 'tokenUrl / DSH_CALENDAR_TOKEN_URL'],
+        ].filter(([value]) => value === undefined).map(([, field]) => field);
+        if (clientId === undefined || clientSecret === undefined || refreshToken === undefined || tokenUrl === undefined) {
+            throw new ConfigError('dsh-calendar 的 OAuth 凭据不完整：请配置 ' + missing.join('、') +
+                '，然后重启。Google CalDAV 仅支持 OAuth 2.0，应用专用密码无法替代刷新令牌。');
+        }
+        validateOAuthUrl(tokenUrl, 'tokenUrl');
+        return { username: nonEmpty(config?.username) ?? '', password: '', oauth: { tokenUrl, clientId, clientSecret, refreshToken } };
+    }
     const username = nonEmpty(config?.username);
     const password = nonEmpty(config?.password) ?? nonEmpty(env.DSH_CALENDAR_PASSWORD);
     if (username === undefined) {
         throw new ConfigError('dsh-calendar 未配置 username：请在 profile 的 cordis.patch.yml 覆盖 calendar 行的 config，' +
-            '填上 CalDAV 账号（Google / iCloud 为账号邮箱）后重启。');
+            '填上 CalDAV 账号（iCloud 为账号邮箱）后重启。');
     }
     if (password === undefined) {
         throw new ConfigError('dsh-calendar 未配置密码：请设置环境变量 DSH_CALENDAR_PASSWORD，' +
-            '或在 profile 的 cordis.patch.yml 覆盖 calendar 行的 password（Google / iCloud 请用应用专用密码）后重启。');
+            '或在 profile 的 cordis.patch.yml 覆盖 calendar 行的 password（iCloud 请用应用专用密码）后重启。');
     }
-    const caldavUrl = buildCaldavUrl(config ?? {}, provider);
-    return { provider, caldavUrl, username, password, proxyUrl: nonEmpty(config?.proxyUrl) ?? '' };
+    return { username, password };
 }
 /** 依据 provider 预设或手填字段拼出日历集合 URL。 */
 export function buildCaldavUrl(config, provider) {

package/lib/oauth.d.ts

@@ -0,0 +1,7 @@
+import type { CalendarOAuthCredentials } from './config.js';
+export declare class OAuthError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** tsdav 管理 token/expiry；此层补上失败校验、取消、代理与不泄露凭据的错误。 */
+export declare function createOAuthFetch(config: CalendarOAuthCredentials, transport: typeof fetch, calendarUrl: string): typeof fetch;

package/lib/oauth.js

@@ -0,0 +1,85 @@
+/** 请求时刷新 OAuth 头；不把 Bearer token 固定到长期缓存的 DAV 客户端。 */
+import { getOauthHeaders } from 'tsdav';
+export class OAuthError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'OAuthError';
+    }
+}
+/** tsdav 管理 token/expiry；此层补上失败校验、取消、代理与不泄露凭据的错误。 */
+export function createOAuthFetch(config, transport, calendarUrl) {
+    const calendarOrigin = new URL(calendarUrl).origin;
+    let credentials = { ...config };
+    const tokenFetch = async (input, init) => {
+        const response = await transport(input, { ...init, redirect: 'error' });
+        if (!response.ok) {
+            // 不读取/回显响应正文：服务端可能原样回显 client secret 或 refresh token。
+            throw new OAuthError('OAuth 令牌刷新失败（HTTP ' + response.status +
+                '）：请检查 clientId、clientSecret、refreshToken；授权撤销或过期时请重新授权。', response.status);
+        }
+        let body;
+        try {
+            body = await response.clone().json();
+        }
+        catch {
+            throw new OAuthError('OAuth 令牌端点返回了无效 JSON；未发送日历请求。');
+        }
+        if (body === null || typeof body !== 'object' || typeof body.access_token !== 'string' || !/^[A-Za-z0-9._~+\/-]+=*$/.test(body.access_token)
+            || (body.token_type !== undefined && String(body.token_type).toLowerCase() !== 'bearer')
+            || (body.expires_in !== undefined && (typeof body.expires_in !== 'number' || !Number.isFinite(body.expires_in) || body.expires_in <= 0))
+            || (body.refresh_token !== undefined && (typeof body.refresh_token !== 'string' || body.refresh_token.trim() === ''))) {
+            throw new OAuthError('OAuth 令牌响应缺少有效的 Bearer access_token 或有效期；未发送日历请求。');
+        }
+        return response;
+    };
+    return async (input, init) => {
+        const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        signal?.throwIfAborted();
+        // 日历对象 href 属于服务端数据；不可用它把 Bearer token 带到其它源或 HTTP。
+        const requestUrl = new URL(input instanceof Request ? input.url : String(input));
+        if (requestUrl.origin !== calendarOrigin || requestUrl.username !== '' || requestUrl.password !== '') {
+            throw new OAuthError('OAuth 日历请求拒绝跨源或带内嵌凭据的对象地址；请检查 caldavUrl 与服务器返回的 href。');
+        }
+        // 每次请求用自己的快照与 signal；并发调用不会共享某一次调用的取消信号。
+        const previous = credentials;
+        const snapshot = { ...previous };
+        // 提前 30 秒刷新，避免传输过程中到期。
+        if ((snapshot.expiration ?? 0) <= Date.now() + 30_000)
+            snapshot.expiration = 0;
+        let headers;
+        try {
+            const result = await getOauthHeaders(snapshot, { signal }, tokenFetch);
+            signal?.throwIfAborted();
+            if (!result.headers.authorization)
+                throw new OAuthError('OAuth 未取得访问令牌；请重新授权。');
+            headers = result.headers;
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (error instanceof OAuthError)
+                throw error;
+            throw new OAuthError('OAuth 令牌请求失败：请检查网络、proxyUrl 与 tokenUrl，然后重试。');
+        }
+        // 只有实际刷新的调用才更新缓存，避免使用旧快照的并发读取覆盖新令牌。
+        if (snapshot.accessToken !== previous.accessToken || snapshot.expiration !== previous.expiration || snapshot.refreshToken !== previous.refreshToken) {
+            credentials = snapshot;
+        }
+        const requestHeaders = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        for (const [name, value] of Object.entries(headers))
+            requestHeaders.set(name, value);
+        let response;
+        try {
+            response = await transport(input, { ...init, headers: requestHeaders, redirect: 'error' });
+        }
+        catch {
+            signal?.throwIfAborted();
+            throw new OAuthError('OAuth 日历请求失败：请检查网络、proxyUrl 与日历地址；请求不允许重定向。');
+        }
+        // 不自动重放写请求；下一次调用会刷新，不复用已被服务端拒绝的 token。
+        if (response.status === 401 && credentials.accessToken === snapshot.accessToken)
+            credentials = { ...credentials, expiration: 0 };
+        return response;
+    };
+}

package/lib/tools.d.ts

@@ -27,4 +27,4 @@ export interface CalendarToolDefinition {
     timeoutMs?: number;
 }
 /** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
-export declare function buildCalendarTools(config: CalendarConfig | undefined): CalendarToolDefinition[];
+export declare function buildCalendarTools(config: CalendarConfig | undefined, env?: NodeJS.ProcessEnv): CalendarToolDefinition[];

package/lib/tools.js

@@ -5,13 +5,19 @@
  * @module dsh-calendar/tools
  */
 import { CalendarService } from './caldav.js';
-import { resolveConfig } from './config.js';
+import { CALENDAR_PROVIDERS, buildCaldavUrl, resolveAuthMethod, resolveConfig, resolveCredentials, validateOAuthUrl, } from './config.js';
 import { compileParameters } from './parameters.js';
 const EVENT_SCHEMA = { type: 'object', additionalProperties: true };
 const TIMEOUT_MS = 60000;
 function asRecord(args) {
     return typeof args === 'object' && args !== null ? args : {};
 }
+function executionSignal(exec) {
+    if (typeof exec !== 'object' || exec === null)
+        return undefined;
+    const signal = exec.signal;
+    return signal instanceof AbortSignal ? signal : undefined;
+}
 function optionalString(args, key) {
     const value = args[key];
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
@@ -97,8 +103,19 @@ function buildSearchFilter(query) {
     };
 }
 /** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
-export function buildCalendarTools(config) {
-    const service = () => new CalendarService(resolveConfig(config));
+export function buildCalendarTools(config, env = process.env) {
+    let cachedKey;
+    let cachedService;
+    const service = () => {
+        const resolved = resolveConfig(config, env);
+        // 闭包内比较，不写日志或磁盘；凭据/端点变化时不复用旧 token。
+        const key = JSON.stringify(resolved);
+        if (cachedService === undefined || cachedKey !== key) {
+            cachedService = new CalendarService(resolved);
+            cachedKey = key;
+        }
+        return cachedService;
+    };
     const list = {
         name: 'calendar_list',
         description: '列出某时间段内的日历事件（默认未来 7 天）。start/end 为 ISO 8601 时间（含时区偏移，如 2025-01-01T09:00:00+08:00），全天事件返回 YYYY-MM-DD。默认展开重复事件（RRULE）：每个实例作为独立行返回，start/end 为该次发生时间，并带 isOccurrence=true 与 seriesStart（系列原开始时间）；非重复事件保持单行且 isOccurrence=false。expand=false 时重复事件按原始单条返回并带 rrule 字段。maxOccurrences 为每个重复事件的展开次数上限。返回每个事件的稳定标识 uid，供 calendar_update / calendar_delete 使用。',
@@ -128,7 +145,7 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const now = new Date();
             const defaultEnd = new Date(now.getTime() + 7 * 24 * 3600 * 1000);
@@ -139,7 +156,7 @@ export function buildCalendarTools(config) {
             assertTimeRange(start, end);
             const expand = booleanWithDefault(input, 'expand', true);
             const maxOccurrences = clampedInteger(input, 'maxOccurrences', 30, 1, 200);
-            const events = sortEvents(await service().list(start, end, { expand, maxOccurrences }));
+            const events = sortEvents(await service().list(start, end, { expand, maxOccurrences }, executionSignal(exec)));
             return { count: events.length, start, end, events };
         },
         timeoutMs: TIMEOUT_MS,
@@ -168,7 +185,7 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: '已新建事件：' + formatEvent(event) }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const summary = requiredString(input, 'summary', '事件标题');
             const start = requiredString(input, 'start', '开始时间');
@@ -189,7 +206,7 @@ export function buildCalendarTools(config) {
                 ...(allDay !== undefined ? { allDay } : {}),
                 ...(rrule !== undefined ? { rrule } : {}),
             };
-            const created = await service().create(fields);
+            const created = await service().create(fields, executionSignal(exec));
             return { created };
         },
         timeoutMs: TIMEOUT_MS,
@@ -219,7 +236,7 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: '已更新事件：' + formatEvent(event) }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const uid = requiredString(input, 'uid', '事件 uid');
             const changes = {};
@@ -248,7 +265,7 @@ export function buildCalendarTools(config) {
             const rrule = optionalString(input, 'rrule');
             if (rrule !== undefined)
                 changes.rrule = rrule;
-            const updated = await service().update(uid, changes);
+            const updated = await service().update(uid, changes, executionSignal(exec));
             return { updated };
         },
         timeoutMs: TIMEOUT_MS,
@@ -275,10 +292,10 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: '已删除事件：uid=' + result.uid }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const uid = requiredString(input, 'uid', '事件 uid');
-            const result = await service().delete(uid);
+            const result = await service().delete(uid, executionSignal(exec));
             return { deleted: true, uid: result.uid, href: result.href };
         },
         timeoutMs: TIMEOUT_MS,
@@ -309,11 +326,11 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const query = requiredString(input, 'query', '搜索关键词');
             const limit = clampedInteger(input, 'limit', 50, 1, 200);
-            const all = await service().all();
+            const all = await service().all(executionSignal(exec));
             const matched = sortEvents(all).filter(buildSearchFilter(query)).slice(0, limit);
             return { query, count: matched.length, events: matched };
         },
@@ -321,7 +338,7 @@ export function buildCalendarTools(config) {
     };
     const health = {
         name: 'calendar_health',
-        description: 'dsh-calendar 自检：检查 CalDAV 配置完整性（服务商/日历地址/账号/密码），不发起网络连接。遇到问题时先运行本工具定位。',
+        description: 'dsh-calendar 自检：检查 CalDAV 配置完整性（服务商/日历地址/Basic 或 OAuth 凭据），不发起网络连接或验证账号授权。遇到问题时先运行本工具定位。',
         parameters: compileParameters({}),
         output: {
             schema: { type: 'object', additionalProperties: true },
@@ -336,29 +353,44 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute() {
+        async execute(_args, exec) {
+            executionSignal(exec)?.throwIfAborted();
             const checks = [];
-            let ok = true;
-            const provider = (config?.provider ?? 'custom');
-            checks.push({ name: '服务商', ok: true, detail: provider });
-            const hasUrl = typeof config?.caldavUrl === 'string' && config.caldavUrl.trim() !== '';
-            const derivable = provider === 'google' || provider === 'nextcloud' || provider === 'icloud';
-            if (hasUrl || derivable) {
-                checks.push({ name: '日历地址', ok: true, detail: hasUrl ? '已配置 caldavUrl' : provider + ' 预设可推导' });
+            const rawProvider = config?.provider;
+            const provider = rawProvider === undefined || rawProvider === null || rawProvider === '' ? 'custom' : String(rawProvider);
+            const providerOk = CALENDAR_PROVIDERS.includes(provider);
+            checks.push({ name: '服务商', ok: providerOk, detail: providerOk ? provider : '不支持 ' + provider + '；只支持 ' + CALENDAR_PROVIDERS.join(' / ') });
+            try {
+                const endpoint = buildCaldavUrl(config ?? {}, provider);
+                if (resolveAuthMethod(config) === 'oauth')
+                    validateOAuthUrl(endpoint, 'caldavUrl');
+                checks.push({ name: '日历地址', ok: true, detail: '已解析为 ' + endpoint });
+            }
+            catch (error) {
+                checks.push({ name: '日历地址', ok: false, detail: error instanceof Error ? error.message : String(error) });
+            }
+            try {
+                if (resolveAuthMethod(config) === 'oauth') {
+                    checks.push({ name: '认证方式', ok: true, detail: 'OAuth 2.0（无需 username/password）' });
+                }
+                else {
+                    const hasUser = typeof config?.username === 'string' && config.username.trim() !== '';
+                    checks.push({ name: '账号', ok: hasUser, detail: hasUser ? '已配置 Basic 账号' : '未配置：请填 username（iCloud 为账号邮箱）' });
+                }
+            }
+            catch (error) {
+                checks.push({ name: '认证方式', ok: false, detail: error instanceof Error ? error.message : String(error) });
+            }
+            try {
+                const credentials = resolveCredentials(config, env);
+                checks.push({ name: '认证凭据', ok: true, detail: credentials.oauth === undefined
+                        ? '已配置 Basic 凭据；仅检查配置，未联网验证'
+                        : '已配置 clientId、clientSecret、refreshToken 与 tokenUrl；仅检查配置，未联网验证' });
             }
-            else {
-                ok = false;
-                checks.push({ name: '日历地址', ok: false, detail: '未配置：请在 profile 的 cordis.patch.yml 里给 calendar 行填 caldavUrl' });
+            catch (error) {
+                checks.push({ name: '认证凭据', ok: false, detail: error instanceof Error ? error.message : String(error) });
             }
-            const hasUser = typeof config?.username === 'string' && config.username.trim() !== '';
-            checks.push({ name: '账号', ok: hasUser, detail: hasUser ? '已配置' : '未配置：请填 username（Google/iCloud 为账号邮箱）' });
-            if (!hasUser)
-                ok = false;
-            const hasPass = typeof config?.password === 'string' && config.password.trim() !== '';
-            checks.push({ name: '密码', ok: hasPass, detail: hasPass ? '已配置' : '未配置：请填 password 或环境变量 DSH_CALENDAR_PASSWORD（Google/iCloud 用应用专用密码）' });
-            if (!hasPass)
-                ok = false;
-            return { ok, plugin: 'dsh-calendar', checks };
+            return { ok: checks.every((check) => check.ok === true), plugin: 'dsh-calendar', checks };
         },
         timeoutMs: TIMEOUT_MS,
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-calendar",
-  "version": "0.4.0",
-  "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
+  "version": "0.5.0",
+  "description": "DeepSeek Harness 日历插件：CalDAV 日程查询、创建、修改、删除与搜索，支持 Google OAuth 2.0、iCloud、Nextcloud、自定义服务及离线配置自检。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -16,7 +16,8 @@
   "files": [
     "lib",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "README.en.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",