From 6857a116ce246511ab086db73204f5a84bb629a3 Mon Sep 17 00:00:00 2001 From: sudoHG Date: Tue, 3 Nov 2026 08:56:38 +0800 Subject: [PATCH 1/2] Prepare version and documentation for v0.5.0 --- CHANGELOG.md | 27 +++++++++++++++++-- README.md | 14 +++++----- README.zh-CN.md | 14 +++++----- Sources/AskKeyBroker/AskKeyVersion.swift | 2 +- docs/adr/0002-broker-and-approval-protocol.md | 2 +- docs/testing.md | 16 ++++++----- 6 files changed, 52 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4567ff..369cc32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,34 @@ Notable changes to AskKey are documented here, grouped by release and change type. -## [Unreleased] +## [0.5.0] - 2026-11-03 + +### Added + +- Read cards for grouped credentials offer one timed allowance for the eligible credentials listed in Details. Later additions to the group are excluded, and an earlier member expiry limits the whole allowance. +- The library lists active timed allowances at the top, with remaining time and revocation actions, even when a search or group filter hides their credentials. A group grant appears once with all covered credentials. +- **End Timed Allow on Lock** in Settings is off by default. Turning it on or off requires system authentication. + +### Changed + +- Clicking a pending-request reminder while management is locked opens the approval prompt directly, keeping management locked on its remembered page. With no pending requests, the click only brings the window forward. This replaces the 0.4.0 behavior of opening Pending requests after management unlocks. +- A credential covered by a group allowance shows **Revoke Group Allowance**; revoking from any member ends the whole grant. + +### Fixed + +- Clicking an agent write-failure notification brings Ask Key forward without opening Pending requests. +- Lock, sleep and user-switch handling runs Vault and Keychain work off the main thread, keeping the interface responsive. With End Timed Allow on Lock enabled, timed authority is refused during queued session-ending events. + +### Security + +- Once this process adopts **End Timed Allow on Lock** as enabled, screen lock, sleep and user switch end single and group timed allowances, cancel unconsumed timed approvals and invalidate prepared timed runtime authorizations. A prepared run containing a timed credential is cancelled as a whole. New timed grants are refused while locked, asleep or switched out, including an unknown screen state. Turning the setting off does not revive revoked authority. +- A remote opt-in not yet adopted is checked at the next ending event through a Keychain policy read, which can fail, or at the next agent request. Allow credentials, once-only approvals, pending requests and management sessions keep their existing behavior, except for prepared runs that also contain a timed credential. Already delivered material cannot be retracted. +- A group allowance covers the approved snapshot of visible, unexpired credentials outside the Recycle Bin, bound by credential ID and component metadata, for the whole local macOS user. Its shared deadline is capped by the configured duration and earliest member expiry. A member's metadata, permission or group change removes that member; explicit revocation, expiry, revoke-all and pause end the whole grant. Writes still need separate approval. See [SECURITY.md](SECURITY.md) for the full boundaries, including sleep and cross-process limitations. ### Upgrade notes -- After enabling the option to end timed allowances on screen lock or sleep, downgrading to an older build makes Agent access settings fail verification and requires authenticated recovery in that build. +- Upgrading from 0.4.0 does not migrate the library. Credentials, permissions and valid Agent access settings are kept without a Resume step; **End Timed Allow on Lock** starts off. +- Downgrading to 0.4.0 with the setting off changes nothing. With it on, 0.4.0 cannot verify the saved Agent access settings and pauses Agent access. Its authenticated **Resume Agent Access** restores all Agent access settings to defaults. Upgrading again before Resume preserves the saved settings. Turn the setting off before downgrading. ## [0.4.0] - 2026-10-28 diff --git a/README.md b/README.md index bc6ed40..b6dcec0 100644 --- a/README.md +++ b/README.md @@ -93,7 +93,9 @@ Each credential has one permission: | Ask every time (default) | Every use waits for your approval. | | Hidden | Not in the agent catalog; agents cannot request it. | -When you approve a read, you choose **Once** or a **Timed allowance**: a number of minutes during which that credential can be read without asking again, until it ends or you revoke it. Pending requests expire after five minutes. +When you approve a read, you choose **Allow Once** or a timed allowance: a number of minutes during which that credential can be read without asking again, until it ends or you revoke it. For a grouped credential, you can also allow the eligible credentials listed in **Details** together. Later additions are excluded, and the whole allowance ends at the earliest member expiry if that is sooner. Active allowances appear at the top of the library with remaining time and revocation actions; **Revoke Group Allowance** ends the whole grant. Pending requests expire after five minutes. + +In **Settings**, **End Timed Allow on Lock** is off by default and requires system authentication to turn on or off. Once enabled in this process, screen lock, sleep or user switch ends single and group timed allowances and unconsumed timed approvals, and cancels prepared runs containing a timed credential. New timed grants are refused while locked, asleep or switched out, including when the screen state is unknown. See [SECURITY.md](SECURITY.md) for the adoption and sleep limitations. Agents can also write: create, modify or delete a credential, set its usage instructions and group, or move credentials and create, rename or delete groups in one batch. Every write needs your approval for that operation (a batch is approved once), the approval is tied to the exact content you were shown, and it cannot be reused for another change. Permanent deletion stays in the app. @@ -131,17 +133,17 @@ What Ask Key does not guarantee: - An approved target can print, copy or forward what it receives. - Caller names and purposes are declared by the agent. They help you read a request; they are not verified identity. - Another process running as the same macOS user may be able to read material after an approved delivery. Hidden keeps a credential out of the agent catalog but does not defend against that. -- A timed allowance covers the credential for the whole local user, not one agent client. +- A timed allowance covers one credential or the explicitly approved group snapshot for the whole local user, not one agent client. Later group additions are excluded; writes still need separate approval. ## Upgrade -Before updating to 0.4.0, quit Ask Key and back up the library folder at `~/Library/Application Support/AskKey`. Download and verify the new DMG as described in [Install](#install), replace `/Applications/Ask Key.app` with the app from the new DMG, then open Ask Key from Applications. +Before updating to 0.5.0, quit Ask Key. Download and verify the new DMG as described in [Install](#install), replace `/Applications/Ask Key.app` with the app from the new DMG, then open Ask Key from Applications. -On first launch, 0.4.0 migrates the library once, including Hidden credentials and those in the Recycle Bin. Your credentials and their permissions are kept; valid 0.3.2 Agent access settings are preserved without a Resume step. **A migrated library cannot be opened by 0.3.2, and there is no reverse migration.** Ask Key has no built-in backup or recovery; keep the originals of your credentials elsewhere as well. +Upgrading from 0.4.0 does not migrate the library or require a library backup for this upgrade. Credentials, permissions and valid Agent access settings are kept without a Resume step. **End Timed Allow on Lock** starts off. Ask Key has no built-in backup or recovery; keep the originals of your credentials elsewhere as well. -If a credential cannot be migrated, management stays available and names it after unlock. Fix it in the editor or permanently delete it from the Recycle Bin, then reopen Ask Key. Agent access stays off until the migration completes. +Downgrading to 0.4.0 with the setting off changes nothing. **Turn it off before downgrading.** With it on, 0.4.0 cannot verify the saved Agent access settings and pauses Agent access; choosing **Resume Agent Access** there and authenticating restores all Agent access settings to defaults. Upgrading again before Resume preserves the saved settings. -MCP clients must now pass an absolute `cwd` to `run`, including when resuming an approval. CLI `run` continues to use the terminal's current directory. +For upgrades from 0.3.2 or earlier, also read the migration and compatibility notes for the intervening versions in [CHANGELOG.md](CHANGELOG.md#040---2026-10-28). Watch [GitHub Releases](https://github.com/sudoHG/AskKey/releases) for new versions; there is no automatic update. diff --git a/README.zh-CN.md b/README.zh-CN.md index 14cd8ad..334b1c3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -93,7 +93,9 @@ helper 位于应用包内的 `Contents/Helpers/askkey`。目标进程只会拿 | 每次询问（默认） | 每次使用都要等你批准。 | | 隐藏 | 不出现在 Agent 目录里，Agent 无法请求。 | -批准读取时，你可以选择“仅本次”或“限时允许”：在设定的分钟数内，这份凭证可以不再询问直接读取，到期或被你撤销后失效。待处理的请求 5 分钟后过期。 +批准读取时，你可以选择“允许本次”或“限时允许”：在设定的分钟数内，这份凭证可以不再询问直接读取，到期或被你撤销后失效。如果凭证属于某个分组，还可以一次允许“详细信息”中列出的所有符合条件的凭证，之后加入分组的凭证不在其中。如果某份凭证更早到期，整个分组的限时允许也会同时结束。凭证库顶部会列出有效的限时允许、剩余时间和撤销按钮；“撤销分组限时允许”会结束整个分组的这次授权。待处理的请求 5 分钟后过期。 + +“设置”中的“锁屏时结束限时允许”默认关闭，开启和关闭都需要系统验证。本次运行采用开启状态后，锁屏、睡眠或切换用户会结束单份凭证和分组的限时允许，取消尚未使用的限时批准，以及包含限时凭证的待执行命令。锁屏、睡眠、用户已切换或屏幕状态不明时，不能授予新的限时允许。设置何时生效及睡眠检测的限制见 [SECURITY.md](SECURITY.md)。 Agent 也能写入：新建、修改或删除凭证，设置使用说明和分组，或者一次性批量移动凭证、新建、重命名和删除分组。每次写入都要你对这一次操作批准（批量操作批准一次即可）。批准绑定的是你看到的那份具体内容，不能挪用到另一次修改上。永久删除只能在应用里进行。 @@ -131,17 +133,17 @@ Claude Code、Codex、Cursor 和 Grok CLI。在应用的 **Agent 接入**页面 - 获准的目标程序可以把收到的内容打印、复制或转发出去。 - 调用方名称和用途由 Agent 自行声明，只是帮你看懂请求，不是经过验证的身份。 - 同一 macOS 用户下的其他进程，可能在交付之后读取到相关内容。“隐藏”只是让凭证不进入 Agent 目录，防不住这类旁路。 -- 限时允许针对的是整个本机用户下的这份凭证，而不是某一个 Agent 客户端。 +- 限时允许针对的是整个本机用户下的一份凭证或明确批准的分组凭证快照，而不是某一个 Agent 客户端。之后加入分组的凭证不在其中；写操作仍需单独批准。 ## 升级 -更新到 0.4.0 前，先退出请旨，并备份 `~/Library/Application Support/AskKey` 凭证库文件夹。按[安装](#安装)中的步骤下载并校验新版 DMG，用其中的应用替换 `/Applications/Ask Key.app`，然后从“应用程序”打开请旨。 +更新到 0.5.0 前，先退出请旨。按[安装](#安装)中的步骤下载并校验新版 DMG，用其中的应用替换 `/Applications/Ask Key.app`，然后从“应用程序”打开请旨。 -首次启动时，0.4.0 会迁移一次凭证库，包括隐藏的凭证和回收站中的凭证。凭证及其权限会保留；有效的 0.3.2 Agent 访问设置也会保留，无需恢复 Agent 访问。**迁移后的凭证库无法再用 0.3.2 打开，也无法反向迁移。** 请旨没有内置的备份和恢复功能，请同时在其他地方保留凭证原件。 +从 0.4.0 升级不会迁移凭证库，也无需为本次升级备份凭证库。凭证、权限和有效的 Agent 访问设置会保留，无需“恢复 Agent 访问”；“锁屏时结束限时允许”初始为关闭。请旨没有内置的备份和恢复功能，请同时在其他地方保留凭证原件。 -如果某份凭证无法迁移，管理功能仍然可用，解锁后会列出受影响的凭证名称。请在编辑器中修复，或从回收站中永久删除，再重新打开请旨。迁移完成前，Agent 访问会保持关闭。 +关闭该设置后降级到 0.4.0，不会改变现有状态。**请先关闭，再降级。** 如果开启着降级，0.4.0 会因无法验证已保存的 Agent 访问设置而暂停 Agent 访问；在 0.4.0 中选择“恢复 Agent 访问”并完成系统验证，会把所有 Agent 访问设置恢复为默认值。在执行“恢复 Agent 访问”之前重新升级，已保存的设置不会丢失。 -MCP 客户端调用 `run` 时，现在必须传入绝对路径 `cwd`，等待批准后继续请求时也一样。CLI `run` 仍使用终端的当前目录。 +如果从 0.3.2 或更早版本升级，还需阅读 [CHANGELOG.md](CHANGELOG.md#040---2026-10-28) 中间各版本的迁移和兼容性说明。 请关注 [GitHub Releases](https://github.com/sudoHG/AskKey/releases) 获取新版本；应用没有自动更新功能。 diff --git a/Sources/AskKeyBroker/AskKeyVersion.swift b/Sources/AskKeyBroker/AskKeyVersion.swift index f908ada..d3d132e 100644 --- a/Sources/AskKeyBroker/AskKeyVersion.swift +++ b/Sources/AskKeyBroker/AskKeyVersion.swift @@ -1,4 +1,4 @@ // Product version read by scripts/product-version.sh; distinct from the Broker protocol version. public enum AskKeyVersion { - public static let current = "0.4.0" + public static let current = "0.5.0" } diff --git a/docs/adr/0002-broker-and-approval-protocol.md b/docs/adr/0002-broker-and-approval-protocol.md index e817864..2f04828 100644 --- a/docs/adr/0002-broker-and-approval-protocol.md +++ b/docs/adr/0002-broker-and-approval-protocol.md @@ -15,7 +15,7 @@ Local agents need discovery, approved runtime delivery and separately approved w - The App's local Broker exposes only metadata catalog, runtime execution, frozen credential write/upload/commit, request status/cancel, health and version operations. Permission/group management, access records, stored-value reveal, permanent deletion, local erase and resuming paused access remain authenticated App operations. - Use the existing versioned, length-prefixed socket protocol. Incompatible versions fail closed. Frames, responses, fields, connections, request counts, queues and I/O deadlines have hard limits in [BrokerLimits](../../Sources/AskKeyBroker/BrokerLimits.swift). - Bind approvals to operation ID, request ID, target, operation, immutable payload digest and deadlines. Query and cancellation require the request's unpredictable capability with its ID. Only an identical retransmission reuses an existing operation; changed content is rejected and a new operation requires a new ID. Denial creates no cooldown. -- Pending requests expire after five minutes or an earlier credential deadline. Approval can be consumed at most once for its bound payload. Timed allowances authorize reads of one credential globally for the local macOS user, never agent writes or one particular client. Read approval uses system authentication by default with an explicitly confirmed opt-out; every agent write still requires separate system authentication. +- Pending requests expire after five minutes or an earlier credential deadline. Approval can be consumed at most once for its bound payload. Timed allowances authorize reads of one credential or an explicitly approved group snapshot (see the [group amendment](#amendment-group-timed-read-allowances-240)) globally for the local macOS user, never agent writes or one particular client. Read approval uses system authentication by default with an explicitly confirmed opt-out; every agent write still requires separate system authentication. - Treat caller names, paths, signatures and purposes as unverified display context. Present approval independently of the management session; protect request details when the screen is locked. Opening or expiring management does not itself grant or revoke agent access. - Preserve original authorization through the synchronized final launch check. Revocation, mutation, pause or expiry that wins this boundary prevents launch and cleans temporary material. Reallowing access cannot revive a consumed authorization. Once launch wins, revocation cannot retract delivered material or promise termination of that target. - Commit agent CRUD and its operation receipt in one database transaction. External process execution does not have crash-level exactly-once semantics: retained completion receipts can return status without respawning, while an uncertain outcome is `outcome_unknown` and must not trigger automatic retry. diff --git a/docs/testing.md b/docs/testing.md index 6051d4a..e675282 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -130,20 +130,22 @@ In credential mode each `xcrun notarytool submit … --wait` runs as: ## Pre-release checks on the maintainer's Mac -CI cannot check focus, Touch ID or real clients. Before notarizing, review the release diff for these behaviors, then install the signed `Release` build at `/Applications/Ask Key.app` and walk through this list once with the maintainer. The planner triggers agent requests itself (for example `askkey run --wait-for-approval` with a harmless command that prints no values, or a Codex session); the maintainer only touches the sensor, clicks decisions and reports what they see. Notarize the same build afterwards; its signature hash must match the one tested. +CI cannot check focus, Touch ID or real clients. Before notarizing, review the release diff for these behaviors, then install the signed `Release` build at `/Applications/Ask Key.app` and walk through this list once with the maintainer. The planner triggers agent requests itself (for example `askkey run --wait-for-approval` with a harmless command that prints no values, or a Codex session), one request at a time with explicit instructions; delay requests that coincide with screen lock so the maintainer never waits at the lock screen. The maintainer only touches the sensor, clicks decisions and reports what they see. Notarize the same build afterwards; its signature hash must match the one tested. Device checks remain `NOT_VERIFIED` until performed; passing synthetic tests or CI is not device verification. - When a release adds a library migration, have the maintainer back up `~/Library/Application Support/AskKey` to a safe place in Finder before installing; agents never read or copy the production library. Review the release's upgrade notes for migration and downgrade limits. Obtain explicit maintainer approval before installation, quit the old app before replacing it, and launch from Applications with a clean environment rather than a terminal carrying Orca or `CODEX_HOME` variables. -- Check the release version and Broker health. After the upgrade, the library opens without a component-metadata warning, credential counts and names are unchanged, and Agent access settings are kept. Quit and launch again to confirm the same state. If migration fails for a credential, management should remain available and name it after unlock, with editor repair or permanent deletion from the Recycle Bin followed by reopening as the next step; do not alter real credentials to manufacture this failure. -- With Simplified Chinese first in the Mac's preferred languages and the app language set to Follow System, Finder and the Touch ID prompt show 请旨; with English first, both show Ask Key. Finder can retain a stale name in the Launch Services cache until the app is re-registered or the Mac restarts. +- Check the release version and Broker health. For 0.4.0 → 0.5.0, no library migration or library backup is required: the library opens without a component-metadata warning, credential counts and names are unchanged, Agent access is not paused, and no Resume banner appears. Read authentication and timed-allowance settings are kept, and End Timed Allow on Lock starts off. Quit and launch again to confirm the same state. For a release that does migrate, if migration fails for a credential, management should remain available and name it after unlock, with editor repair or permanent deletion from the Recycle Bin followed by reopening as the next step; do not alter real credentials to manufacture this failure. +- With Simplified Chinese first in the Mac's preferred languages and the app language set to Follow System, Finder and the Touch ID prompt show 请旨; with English first, both show Ask Key. Finder can retain a stale name in the Launch Services cache until the app is re-registered or the Mac restarts. Check the group read card and Settings in both languages, including the localized End Timed Allow on Lock and Revoke Group Allowance labels. - Compare the release machine's `xcrun --sdk macosx --show-sdk-version` and executable marker with the CI marker logs, including the informational window check. If the release SDK differs from the SDK that passed the CI window check (or that job has no passing result), the planner runs the visible management-window check against an isolated dev build marked with the release SDK, with the maintainer present and explicitly approving the local desktop interaction. Check repeated activation for stable size and position before notarization. -- Every Touch ID entry: unlock management, reveal and copy a value, revoke a timed allowance, permanently delete, replace on import, settings actions, approving a read and a write. The prompt accepts a finger without a click. +- Every Touch ID entry: unlock management, reveal and copy a value, revoke a single or group timed allowance, permanently delete, replace on import, settings actions, approving a single or group read and a write. The prompt accepts a finger without a click. Turning End Timed Allow on Lock on asks for authentication; cancellation leaves it off. After enabling it, relaunch and confirm it stays on; turning it off also asks for authentication. - With another app's window behind Ask Key, unlock management: Ask Key stays in front afterwards, and its Dock icon does not disappear during the prompt. - With the management window open behind another app, an agent request arrives: only the approval prompt appears; after Allow and Touch ID, focus returns to the other app. -- Read approval Details shows component names and delivery mappings. Run one harmless CLI `askkey run` and one MCP `run` with an explicit absolute `cwd` through the installed helper; each approval shows the directory used by the command. The commands must not print credential values. +- Read approval Details shows component names and delivery mappings. For a grouped credential, in English and Simplified Chinese, Details lists every eligible credential, excludes Hidden, expired and recycled credentials, and shows Expires when a member expires before the selected duration. Later additions are excluded from the grant. Approving the group creates one library row with all covered credentials, remaining time and Revoke Group Allowance; it remains visible through search and group filters. A member's inspector shows Revoke Group Allowance, and revoking it ends the whole grant. Run one harmless CLI `askkey run` and one MCP `run` with an explicit absolute `cwd` through the installed helper; each approval shows the directory used by the command. The commands must not print credential values. - Cancel one approval's Touch ID authentication, then approve a second request: only the first request is cancelled, the second can authenticate, and a finger is accepted without an extra click. - While the management import file picker is open, an agent request updates the pending count and posts a reminder without showing an approval prompt. Closing the picker shows the still-pending prompt. The Dock icon stays visible while a management picker or alert is open. -- Click an approval reminder while Ask Key is running: Pending requests opens after unlock. Quit Ask Key, then click a delivered reminder in Notification Center: Ask Key launches and opens Pending requests after unlock. With unsaved changes in the credential editor, clicking a reminder only brings management forward and preserves the draft. -- If an external or scaled display is available, expand a long approval on a short screen and check that the title and action buttons stay visible. Record when this physical-display check is unavailable instead of treating simulated layout tests as device verification. +- Click an approval reminder while Ask Key is running and management is locked: the pending approval card opens directly, management stays locked, and its remembered page and sidebar selection survive unlocking. With nothing pending, the click only brings the window forward. With management already unlocked, a pending reminder opens Pending requests. With unsaved changes in the credential editor, clicking a reminder only brings management forward and preserves the draft. An agent write-failure notification brings Ask Key forward without jumping to Pending requests. Separately, quit Ask Key and click a delivered reminder in Notification Center to check launch and the queue-dependent behavior above while management stays locked; this cold-launch check remains `NOT_VERIFIED` from v0.4.0 until performed. +- With End Timed Allow on Lock enabled, create one single and one group allowance, lock with ⌃⌘Q for at least five seconds, and unlock: the list is empty and the next read asks again. A request sent just before locking stays pending and posts its reminder. Through five quick lock/unlock cycles, the interface remains responsive. Turn the setting off and confirm allowances survive a lock without a Keychain prompt. +- With the setting enabled, choose Apple menu > Sleep, wake and unlock: allowances are gone, and a new timed approval works immediately after wake. If the maintainer elects to test fast user switch, confirm allowances end on switching away and fresh timed approval works after returning. Passwordless wake is also optional; record either optional check as `NOT_VERIFIED` when omitted. +- If an external or scaled display is available, expand a long group approval on a short screen in English and Simplified Chinese and check that the title and all action buttons stay visible while Details scrolls. Check centred empty states for an empty library, an empty group and a search with no results, with and without an active allowance row above them. Record when the physical-display check is unavailable instead of treating simulated layout tests as device verification. - Clicking the menu-bar item with the management window open behind another app. - The sample prompt from Agent access runs as written in a new client session; each supported client that is installed still reports Connected; Claude Code setup still detects its discovery hooks; an SSH request is reminded to look up credentials first. - After notarization, verify both checksum files in the output directory with `shasum -a 256 -c AskKey-.dmg.sha256` and `shasum -a 256 -c AskKey.dmg.sha256` (replace `` with the release version). Upload all four files (`AskKey-.dmg`, `AskKey-.dmg.sha256`, `AskKey.dmg`, and `AskKey.dmg.sha256`) to the draft release. Obtain the maintainer's explicit approval before pushing the tag or publishing the release, as required by [ADR 0006](adr/0006-release-process.md). From aad996641055b16e46765a4180d42404f45f7c96 Mon Sep 17 00:00:00 2001 From: sudoHG Date: Tue, 3 Nov 2026 09:11:58 +0800 Subject: [PATCH 2/2] Keep v0.5.0 fixes focused on observable behavior --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 369cc32..1f4e974 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,6 @@ Notable changes to AskKey are documented here, grouped by release and change typ ### Fixed - Clicking an agent write-failure notification brings Ask Key forward without opening Pending requests. -- Lock, sleep and user-switch handling runs Vault and Keychain work off the main thread, keeping the interface responsive. With End Timed Allow on Lock enabled, timed authority is refused during queued session-ending events. ### Security