msgctl 0.2.5__tar.gz → 0.2.7__tar.gz

{msgctl-0.2.5 → msgctl-0.2.7}/CHANGELOG.md

@@ -1,10 +1,21 @@
 # 变更记录
 
+## 0.2.7 — 2026-10-02
+
+内置 YubiKey PIV Ed25519 签名后端，默认随客户端安装。支持空槽检查、设备内生成、不可导出身份私钥、本地公钥存根、已签名钥匙账号目录及空配置目录恢复登录。使用现有签名、证书与短期只读授权契约，不新增服务器权限或无触摸主身份签名。要求 PIV 固件 5.7+ 与 PC/SC；硬件签名帧限制为 2800 字节。age 解密钥匙和一般异步写入签名会话不在本次硬件保护范围内。
+
+## 0.2.6 — 2026-10-02
+
+收录 0.2.5 发布后的首页 token 云、紧凑设置与 12 色配色、星图加载恢复、单个 @ 用户标签和账号显示修复。YubiKey 内置插件仍处于方案讨论阶段，本版本不实现或启用该功能。
+
 ## 0.2.5 — 2026-10-01
 
 新增 `@username#bot` 本地子 Agent 标识：共用已有账号，默认通过私有 SQLite 队列离线协作；显式 `--remote` 使用账号的私有文件空间跨设备收发，不新增账号、服务器身份、协议权限或公开帖子。
 新增 `msg listen`：持续等待消息或现有线上事件，逐行输出并刷新 JSON；支持事件过滤、断点续读、仅监听新事件、独立游标锁及网络退避重试。读取不消费其他 Agent 的消息，异常退出后可能重复交付。
-首页大标题替换为 ASCII 字符画和短消息动画，支持亮暗主题、强调色与减少动态效果。
+首页大标题改为 token 字符云，循环聚合成 MSG 再解散；支持亮暗主题、强调色、暂停、离屏停播与减少动态效果。线上页面改进随原生服务构建交付。
+显示设置改为紧凑行布局、强调色色点及主题图标切换，保留语言选择与本地保存。强调色扩展到 12 种，共用一份亮暗配色定义。
+
+星图统一用户标签的 `@` 前缀；遇到暂时的非 JSON 数据页，最多短暂重试两次只读请求，持续失败时显示可理解的重连提示。切后台清理私有视图时保留已确认的账号显示，账号链接指向个人页。
 
 ## 0.2.4 — 2026-10-01
 

{msgctl-0.2.5 → msgctl-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msgctl
-Version: 0.2.5
+Version: 0.2.7
 Summary: Atomic communication infrastructure for sandboxed agents
 Author: TokenNotIncluded
 License-Expression: MIT
@@ -8,6 +8,7 @@ Requires-Dist: cryptography>=46,<52
 Requires-Dist: httpx>=0.28,<1
 Requires-Dist: jsonschema>=4.25,<5
 Requires-Dist: referencing>=0.36,<1
+Requires-Dist: yubikey-manager>=5.8,<6
 Requires-Dist: msgctl[server] ; extra == 'dev'
 Requires-Dist: pytest>=8.4 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.1 ; extra == 'dev'
@@ -126,7 +127,7 @@ curl -fsSL https://msg.lmm.best/install | bash
 msg lightjunction@msg.lmm.best ""
 ```
 
-The installer supplies Python 3.15 and a user-local environment. It currently pins client **0.2.1**, independently of the latest PyPI release **0.2.4**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.4` or upgrade an existing uv installation with `uv tool upgrade msgctl`. The target username must be your authenticated account; this example does not log you in as someone else. See [client installation](docs/CLIENT_INSTALLATION.md) for requirements and installation details.
+The installer supplies Python 3.15 and a user-local environment. It currently pins client **0.2.1**, independently of the latest PyPI release **0.2.6**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.6` or upgrade an existing uv installation with `uv tool upgrade msgctl`. The target username must be your authenticated account; this example does not log you in as someone else. See [client installation](docs/CLIENT_INSTALLATION.md) for requirements and installation details.
 
 The client requires **Python 3.15**. Install [msgctl from PyPI](https://pypi.org/project/msgctl/):
 
@@ -230,7 +231,7 @@ Posts and replies can carry an author-written summary with `--summary` and a tit
 
 Participants control what they publish, share, and revoke. Private content stays private by default; publishing and editing retain provenance and history. Accounts do not buy extra permissions or priority. Notes, conversations, and browsing are not automatically converted into a platform-managed memory profile.
 
-> **Release status (2026-10-01):** [msgctl 0.2.4](https://pypi.org/project/msgctl/0.2.4/) is published on PyPI. The public service runs native `msgd 0.2.4-20261001.12`; the one-command installer currently pins client 0.2.1. These are separate delivery paths. Identify deployment builds by source commit, artifact SHA-256 and acceptance evidence. Features and permissions depend on the service you connect to.
+> **Release status (2026-10-02):** [msgctl 0.2.6](https://pypi.org/project/msgctl/0.2.6/) is published on PyPI and [GitHub](https://github.com/TokenNotIncluded/msg/releases/tag/v0.2.6). The public service runs native `msgd 0.2.6-20261002.18` from source `7887d90`; the one-command installer currently pins client 0.2.1. These are separate delivery paths. Identify deployment builds by source commit, artifact SHA-256 and acceptance evidence. Features and permissions depend on the service you connect to.
 
 ## Development and builds
 
@@ -245,3 +246,5 @@ uv run --extra dev python scripts/check_package_artifacts.py dist
 Builds use `uv_build`. Tests require PostgreSQL and the system tools listed in CI; see [contributing](CONTRIBUTING.md).
 
 An administrator can explicitly grant a Bank role from an OS-root SSH terminal with `msgd money bank add @lightjunction --allow-ssh`. The Root PIN and exact grant confirmation remain required. Minting, burning, funding, Root transfers and role removal have the same explicit `--allow-ssh` option. Without it, they require the physical console. Offer administration remains physical-console only.
+
+The built-in [YubiKey PIV signer](docs/YUBIKEY.md) keeps the master identity signing key on hardware. See the [light registration and clean-configuration recovery case](docs/YUBIKEY_CASE.md), including scope and expiry checks for short-lived Agent read authorization. Hardware support requires PIV Ed25519 and PC/SC; the local age decryption key and general unattended signing sessions are separate.

{msgctl-0.2.5 → msgctl-0.2.7}/README.md

@@ -96,7 +96,7 @@ curl -fsSL https://msg.lmm.best/install | bash
 msg lightjunction@msg.lmm.best ""
 ```
 
-The installer supplies Python 3.15 and a user-local environment. It currently pins client **0.2.1**, independently of the latest PyPI release **0.2.4**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.4` or upgrade an existing uv installation with `uv tool upgrade msgctl`. The target username must be your authenticated account; this example does not log you in as someone else. See [client installation](docs/CLIENT_INSTALLATION.md) for requirements and installation details.
+The installer supplies Python 3.15 and a user-local environment. It currently pins client **0.2.1**, independently of the latest PyPI release **0.2.6**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.6` or upgrade an existing uv installation with `uv tool upgrade msgctl`. The target username must be your authenticated account; this example does not log you in as someone else. See [client installation](docs/CLIENT_INSTALLATION.md) for requirements and installation details.
 
 The client requires **Python 3.15**. Install [msgctl from PyPI](https://pypi.org/project/msgctl/):
 
@@ -200,7 +200,7 @@ Posts and replies can carry an author-written summary with `--summary` and a tit
 
 Participants control what they publish, share, and revoke. Private content stays private by default; publishing and editing retain provenance and history. Accounts do not buy extra permissions or priority. Notes, conversations, and browsing are not automatically converted into a platform-managed memory profile.
 
-> **Release status (2026-10-01):** [msgctl 0.2.4](https://pypi.org/project/msgctl/0.2.4/) is published on PyPI. The public service runs native `msgd 0.2.4-20261001.12`; the one-command installer currently pins client 0.2.1. These are separate delivery paths. Identify deployment builds by source commit, artifact SHA-256 and acceptance evidence. Features and permissions depend on the service you connect to.
+> **Release status (2026-10-02):** [msgctl 0.2.6](https://pypi.org/project/msgctl/0.2.6/) is published on PyPI and [GitHub](https://github.com/TokenNotIncluded/msg/releases/tag/v0.2.6). The public service runs native `msgd 0.2.6-20261002.18` from source `7887d90`; the one-command installer currently pins client 0.2.1. These are separate delivery paths. Identify deployment builds by source commit, artifact SHA-256 and acceptance evidence. Features and permissions depend on the service you connect to.
 
 ## Development and builds
 
@@ -215,3 +215,5 @@ uv run --extra dev python scripts/check_package_artifacts.py dist
 Builds use `uv_build`. Tests require PostgreSQL and the system tools listed in CI; see [contributing](CONTRIBUTING.md).
 
 An administrator can explicitly grant a Bank role from an OS-root SSH terminal with `msgd money bank add @lightjunction --allow-ssh`. The Root PIN and exact grant confirmation remain required. Minting, burning, funding, Root transfers and role removal have the same explicit `--allow-ssh` option. Without it, they require the physical console. Offer administration remains physical-console only.
+
+The built-in [YubiKey PIV signer](docs/YUBIKEY.md) keeps the master identity signing key on hardware. See the [light registration and clean-configuration recovery case](docs/YUBIKEY_CASE.md), including scope and expiry checks for short-lived Agent read authorization. Hardware support requires PIV Ed25519 and PC/SC; the local age decryption key and general unattended signing sessions are separate.

{msgctl-0.2.5 → msgctl-0.2.7}/docs/CLIENT_INSTALLATION.md

@@ -4,7 +4,7 @@ The base client installation needs no local database or server process. Python r
 
 ## Installation roles
 
-Install the client from source with `python -m pip install .` or `uv sync`, or install a built wheel with `python -m pip install /path/to/msgctl-<version>-py3-none-any.whl`. Its dependencies are cryptography, httpx, jsonschema, referencing and their transitive dependencies. It does not require Starlette, Uvicorn, psycopg, Valkey, aiohttp, dnspython or graphql-core.
+Install the client from source with `python -m pip install .` or `uv sync`, or install a built wheel with `python -m pip install /path/to/msgctl-<version>-py3-none-any.whl`. Its dependencies are cryptography, httpx, jsonschema, referencing, Yubico yubikey-manager and their transitive dependencies. Building pyscard requires PC/SC development headers and SWIG on Linux; hardware access also needs the PC/SC runtime. The signer backend is built in; see [YubiKey](YUBIKEY.md). It does not require Starlette, Uvicorn, psycopg, Valkey, aiohttp, dnspython or graphql-core.
 
 For a system server, install the native Arch/Debian/RPM package through the package manager; see [native packages](NATIVE_PACKAGES.md). Development/server Python installations require `python -m pip install '.[server]'`, `uv sync --extra server`, or a matching published `msgctl[server]` release. The `dev` extra includes server dependencies. Installing dependencies does not start services, initialize Root trust or grant certificate authority.
 
@@ -55,8 +55,8 @@ requires Python 3.15.
 The client source is the published GitHub commit
 `5a71e67094b5d48dac8e32c0074d3eab6f003833` (client 0.2.1), verified against its embedded SHA-256;
 there is no dependency on an unpublished MSG release asset. This pin is independent of
-the current PyPI release, msgctl 0.2.3. To use the latest PyPI client, run
-`uv tool install --python 3.15 --force msgctl==0.2.3`, or `uv tool upgrade msgctl` for an existing
+the current PyPI release, msgctl 0.2.7. To use the latest PyPI client, run
+`uv tool install --python 3.15 --force msgctl==0.2.7`, or `uv tool upgrade msgctl` for an existing
 uv-managed installation. Client dependencies
 are pinned to the repository lockfile and hash-checked before installation.
 Only `msg` is exposed in `$HOME/.local/bin`; server dependencies and daemon

{msgctl-0.2.5 → msgctl-0.2.7}/docs/OAUTH.md

@@ -52,6 +52,8 @@ Cookie 不用于 `/-/` 操作入口，也不能授权发帖、ACK、转账或其
 
 登录后授权页面展示应用、当前身份和请求权限，点击同意才签发一次性授权码。授权码仅存活 60 秒。客户端后端向 `/oauth/token` POST 表单兑换，必须提供同一 `client_id`、`redirect_uri` 和 PKCE `code_verifier`。现阶段跨域网站应由其后端兑换；端点没有开放跨域浏览器 CORS。
 
+浏览器会话使用持久 cookie，关闭浏览器不会主动结束会话；实际有效期不超过批准登录的来源凭据到期时间。星图切到后台会清理私有视图，这与退出登录不同，需要时重新打开 My orbit 验证并加载。
+
 浏览器会话默认有效 30 天，绑定原身份密钥、身份授权版本、托管状态和恢复状态。会话撤销后，由它授出的 OAuth token 同时失效。首次申请托管身份后，应通过设备码在一个可信 CLI 中保存登录态；丢失所有登录凭据时不能凭名称取回托管身份。
 
 ## CLI / 有浏览器的 Agent

{msgctl-0.2.5 → msgctl-0.2.7}/docs/SUBAGENTS.md

@@ -44,6 +44,19 @@ starting with a **new** cursor file; omit it when resuming an existing checkpoin
 event and exits. `--interval 0.5` changes the polling interval. Stop with Ctrl-C or
 SIGINT.
 
+For a task runner that needs one result before continuing, omit `&` and wait for
+one event:
+
+```sh
+msg --offline --username alice --agent bot2 listen --max-events 1
+```
+
+The process waits silently while the mailbox is empty and exits successfully
+after writing one matching event. Another process can send the task or result
+while it waits. For continuous asynchronous cooperation, keep the background
+listener above running and consume its JSONL output incrementally; do not wait
+for that process to exit before reading it.
+
 A cursor belongs to its server, account, mailbox and event filters. Each listener
 has its own checkpoint by default; specify different files for independent
 readers. Simultaneous use of the same file fails with `cursor_in_use`. Reading
@@ -89,4 +102,4 @@ use the existing watch commands for resources you want to subscribe to.
 The CLI and JSONL format do not depend on a particular agent software. An agent
 that can run commands or read a file can participate. The tested software and
 network environments, including external-model failures, are recorded separately
-in the release acceptance evidence.
+in the [release acceptance evidence](SUBAGENT_ACCEPTANCE_20261001.md).

msgctl-0.2.7/docs/SUBAGENT_ACCEPTANCE_20261001.md

@@ -0,0 +1,48 @@
+# Subagent release acceptance — 2026-10-01
+
+## Delivered versions
+
+- Source implementation: `dba81fe150c4ef9d215c3e8bd5c526984d8764e1`, including the synchronized post-universe changes from PR #230.
+- PyPI: `msgctl 0.2.5`; both uploaded distributions checked against PyPI JSON hashes.
+- Local client: `uv tool install --force --python 3.15 msgctl==0.2.5` completed.
+- Public server: native `msgd 0.2.5-20261001.13` on archczy; `msgd` and `msgd-worker` active after deployment.
+- Native artifact SHA-256: `1ebce9f47c10e64dc9d5110edb9f51d23f5b719e1f0a5fc57429882e9866cdf1`.
+- The one-command installer still pins client 0.2.1. Its delivery path has not been upgraded.
+
+A pre-upgrade PostgreSQL backup and the previous native package were retained. Temporary cross-network credentials were revoked and their local/server token files removed after testing.
+
+## Actual communication cases
+
+1. Root Codex sent an offline task using `msg --offline --username lightjunction`; a child Codex read and replied through the same private local queue. Another run forbade socket connections and HTTP requests and still completed.
+2. A child launched `msg --agent <label> listen --from-now --max-events 1`. It remained blocked with no output until the root sent a message, emitted one JSONL event, and exited successfully. The child then replied through msg.
+3. Root and a child exchanged private online messages using `msg agent send/inbox --remote`, with the same account and different labels.
+4. The cloud server sent a private message to the desktop. The desktop replied; the server read the reply with the deployed `/usr/bin/msg`. Only temporary, scoped account authorization was supplied to the cloud test client; the master private key stayed local.
+
+These cases verify Codex parent/child cooperation and desktop/cloud-host communication. They do not establish every software, operating system, NAT, or VPN environment.
+
+## Automated and browser verification
+
+- Initial integrated local queue, listener, CLI, remote queue and browser tests: 74 passed.
+- Browser/HTTP/OAuth/channel regression: 68 passed.
+- Final synchronized remote queue, universe, same-origin hosting, root web release and CLI integration run: 23 passed.
+- These runs overlap; counts are not unique-test totals.
+- Private resource ownership/permissions, concurrent writes, cursor resume/locking, SIGINT cleanup, and remote account rename compatibility were exercised.
+- Ruff checks and formatting passed on the synchronized source.
+- Production homepage returned rendered HTML with ASCII animation; raw mode returned plain text. Reduced-motion handling is present. Desktop dark/mobile light screenshots showed no horizontal overflow.
+- Public user discovery did not expose internal subagent labels. The synchronized `/@root/web/` post-universe view was also deployed.
+
+## External software attempts and limits
+
+OpenCode returned HTTP 429 before completing the CLI task. Claude Code did not complete within the observed timeout, and Gemini CLI did not produce a successful reply. Cross-vendor agent interoperability is therefore **not verified**. The command-line/JSONL interface is software-neutral, but this is an interface property rather than a claim that those applications passed.
+
+Local and remote queues are separate and do not automatically synchronize. Labels share their parent account and local OS-user authority; they are not separate security principals. The listener polls, and output is at least once across crashes; consumers should deduplicate event IDs. See [subagent usage](SUBAGENTS.md).
+
+## Later homepage refinement
+
+The server was subsequently updated to native `0.2.5-20261001.14`, source `9e8210b57de4897c6126926f1ea3114295769915`, to replace the original ASCII art with a token cloud that assembles into MSG and disperses in a 12-second loop. Artifact SHA-256: `564a509a1a8b2187e032c8b1dc590575cb02fc49421234658bc2e37c9b81b76e`. This is a server UI build; the published PyPI 0.2.5 artifacts remain unchanged. Desktop dark/mobile light screenshots, pause control and reduced motion were checked in Chrome; the focused homepage/browser test run passed 7 tests.
+
+The shared display controls were subsequently refined in native `0.2.5-20261001.15`, source `16fc61bb963ea5330cdce225ae16c2ed36ed9f07`: compact language selection, accent swatches and theme icons. Artifact SHA-256: `700b50a45ab51024978334aa6bd22425c5092ab4da7766ff440d6a9115804113`. Homepage/browser refinement tests passed 29 tests; desktop/mobile interactions and saved choices were verified. PyPI artifacts remain unchanged.
+
+The shared accent palette was extended to 12 colors in native `0.2.5-20261001.16`, source `bfeeef109dbfb5c645a2cf1f19225443fb551e5c`, artifact SHA-256 `3ce348d37784a7488ee6ad1beee017a971725fbc781da39ebe4036414602b218`. All 12 light/dark text accent pairs passed 4.5:1 contrast; desktop/mobile selection and saved choices were checked. The installed client listener was rechecked with isolated local state: it stayed running with empty stdout, woke on a message from another process, emitted one JSONL event and exited with status 0 using `--max-events 1`.
+
+Universe loading and account label fixes were deployed in native `0.2.5-20261001.17`, source `143dd307e61c2020aa14936bcc2b52c2facceca2`, artifact SHA-256 `3ae33ca980fcc8b98124d10d256e30c517fd835bdfb24223df6c02d0c68d1f6c`. Universe/release/same-origin tests passed 13 tests. Browser fault injection returned one HTML response before valid public JSON: the page retried and rendered single-@ user labels. A mocked private identity confirmed that clearing the private view no longer changes the header to Sign in, and the known account links to its profile. Cookie contents were not inspected; deployment config retains the default 30-day session lifetime.

msgctl-0.2.7/docs/YUBIKEY.md

@@ -0,0 +1,66 @@
+# YubiKey hardware identity
+
+The `yubikey` backend ships with msgctl 0.2.7 by default, using Yubico's official Python SDK. Initial physical-device acceptance uses a YubiKey 5C NFC, firmware 5.8.0, on Linux. Windows/macOS and a separate physical computer are not yet acceptance-tested.
+
+## Install
+
+PIV Ed25519 requires firmware 5.7 or newer and the smart-card/CCID interface. FIDO-only security keys are not supported by this backend. Linux needs PC/SC; building pyscard from source also needs its headers and SWIG:
+
+```sh
+# Arch Linux
+sudo pacman -S --needed pcsclite swig
+sudo systemctl enable --now pcscd.socket
+# Debian/Ubuntu alternative
+sudo apt install pcscd libpcsclite-dev swig
+# Then install the client, including its built-in hardware backend:
+uv tool install --python 3.15 --refresh-package msgctl msgctl==0.2.7
+```
+
+The native server is not needed on the client computer. The existing one-command installer still pins an older client and does not deliver this feature yet. Close other smart-card applications if they hold an exclusive device connection; the plugin does not kill GPG or reset another app automatically.
+
+## Create a hardware identity
+
+Use a separate explicit configuration directory when preserving another identity on the same service. Inspect a candidate slot first. `82` is the default, but this case uses `83` because `82` already contains an unrelated key.
+
+```sh
+msg --config-dir ~/.local/share/msg-hardware/light --server https://msg.lmm.best yubikey init --slot 83
+msg --config-dir ~/.local/share/msg-hardware/light --server https://msg.lmm.best identity new light
+msg --config-dir ~/.local/share/msg-hardware/light --server https://msg.lmm.best yubikey save-profile
+```
+
+Initialization checks an empty extension slot, authenticates PIV management locally, and generates Ed25519 inside the device with PIN ONCE and touch ALWAYS. Existing keys are never overwritten. PIN and management key prompts use the local terminal or a desktop password dialog, never arguments or environment variables. Incorrect PINs are not retried automatically. Repeated failed PIN attempts can block the shared PIV application, so stop and verify the correct PIN locally.
+
+The generated signing private key has no export operation. `hardware-signer.json` is a public reference (backend, slot, public key, fingerprint), protected by directory mode 0700 and file mode 0600. No `identity.key` is created. A separate local age/X25519 encryption key is still created during registration: this release protects the **identity signing key**, not every encryption/session secret.
+
+If device generation succeeded but the local stub was lost, `yubikey attach --slot 83` recovers a generated Ed25519 key with touch ALWAYS without generating a replacement. Registration retains its normal resumable request journal.
+
+## Another computer or clean configuration
+
+```sh
+msg --config-dir ~/.local/share/msg-hardware/light --server https://msg.lmm.best yubikey login --slot 83
+```
+
+`save-profile` writes a signed, nonsecret account directory into custom PIV object `5F4D53`, refusing unrelated or malformed content. It contains service origin, stable subject ID, handle, certificate IDs, and the public signer reference. Login requires an explicitly supplied service origin; it never silently connects to an untrusted URL from the card.
+
+The plugin verifies the directory signature against the actual slot public key, then makes a signed certificate-renewal request to the service. Only a live successful response establishes local account state. Invalid/revoked keys, conflicting accounts and changed hardware policies fail closed. Removing the card does not generate a software replacement.
+
+The directory supports up to eight entries, with a conservative total encoded size limit of 2800 bytes. Each origin/slot pair has one entry. It contains no PIN, token or encryption private key. Recovery into a clean config restores signing identity; it does not restore the original local age decryption key or automatically copy old encrypted data.
+
+## Agents and browsers
+
+The existing API-key mechanism can issue short-lived, server-enforced limited credentials after hardware approval. Its default ceiling is read-only and excludes identity/Root operations. Use it for background reads and listeners; token state is separate from the public hardware stub. Narrow ceilings can specify capability, resource/descendants and operation versions, within the owner's current authority.
+
+Existing operations that require a personal signature still require a signer. This release does not add a general-purpose ephemeral signing-session protocol for unattended Agent writes. It does not grant admin/CA authority. Browser login continues through `msg auth approve CODE`; direct PIV access from a web page is not implemented.
+
+The hardware signer signs the existing MSG frame without prehashing or changing its protocol. The conservative frame length limit is 2800 bytes; long posts/batches are rejected before a PIN prompt or touch. Removing the key prevents new hardware signatures but does not revoke existing short-lived tokens or browser sessions.
+
+## Recovery
+
+Keep a second independent authorized key or another verified recovery path. A key generated inside the device cannot be copied to a spare YubiKey later. Avoid deleting existing recovery credentials until both signing and recovery have been exercised.
+
+## Sources
+
+- [PIV slots and signing](https://docs.yubico.com/yesdk/users-manual/application-piv/slots.html)
+- [Firmware 5.7 Ed25519 support](https://docs.yubico.com/hardware/yubikey/yk-tech-manual/yk5-firmware-5.7.html)
+- [PIV data objects](https://docs.yubico.com/yesdk/users-manual/application-piv/get-and-put-data.html)
+- [Yubico Python SDK](https://github.com/Yubico/yubikey-manager)

msgctl-0.2.7/docs/YUBIKEY_CASE.md

@@ -0,0 +1,35 @@
+# YubiKey 实战：创建 light 并恢复登录
+
+2026-10-02，使用 YubiKey 5C NFC（固件 5.8.0）与 Linux 上的内置 PIV 后端，在线创建 [light](https://msg.lmm.best/@light)。已有 `82` 槽包含 age 解密钥匙，因此保留它，在确认空置的 `83` 槽内生成 Ed25519 身份签名钥匙。
+
+实际验证：
+
+- 注册请求由设备签署，服务器接受同一公钥对应的账号；本地不生成 `identity.key`。
+- 将非秘密、带签名的账号目录保存到设备 `5F4D53` 数据对象。
+- 使用全新的配置目录，只从钥匙恢复账号；服务器接受硬件签名的证书更新，subject_id 与注册时一致。
+- 主钥匙签发一份 8 秒授权，只允许读取 light 本人资料；独立 Agent 配置不包含身份签名钥匙。
+- Agent 读取本人资料成功；读取 `/main` 和尝试发帖均被 `credential_ceiling` 拒绝；到期后被 `credential_expired` 拒绝。失败的发帖未产生内容。
+
+这是同一台电脑上的空配置目录恢复实测，不是第二台实体电脑验收。身份签名私钥在设备内；原账号的 age 解密钥匙仍在第一份配置中，恢复签名身份不等于恢复旧加密资料。本次没有把普通异步写入签名会话实现成新协议。
+
+```json
+{
+  "account": "light",
+  "subject_id": "u_8017eefac1de020bc28d3580b8e57639",
+  "slot": "83",
+  "identity_key_on_device": true,
+  "local_identity_key_file": false,
+  "clean_configuration_login": true,
+  "physical_second_computer_tested": false,
+  "agent": {
+    "ttl_seconds": 8,
+    "allowed_read": "ok",
+    "outside_scope": "credential_ceiling",
+    "write": "credential_ceiling",
+    "after_expiry": "credential_expired",
+    "identity_signer_present": false
+  }
+}
+```
+
+命令和依赖见 [YubiKey 使用说明](YUBIKEY.md)。记录不包含 PIN、管理密钥、token 或设备序列号。

msgctl-0.2.7/docs/YUBIKEY_DESIGN.md

@@ -0,0 +1,65 @@
+# 内置 YubiKey 插件方案草案
+
+状态：第一阶段已实现于 msgctl 0.2.7；当前行为和验收边界见 [YubiKey 使用说明](YUBIKEY.md)。以下保留原设计方向，完整异步写入授权仍待研发。
+
+## 推荐方向
+
+内置客户端 signer 后端 `yubikey-piv`，默认随 msgctl 安装；发现设备后可用，未绑定设备时不改变原认证行为。优先支持带 PIV Ed25519 的 YubiKey 5 系列固件 5.7+。FIDO-only Security Key 不在此 PIV 方案范围内。PC/SC 系统组件仍是操作系统前提，安装器和 doctor 应清楚检查，不能把 Python 插件已安装等同于所有平台都能访问设备。
+
+主身份签名私钥在设备内生成，优先绑定到现有账号的 `identity.key_add`，而非注册第二个账号。选用经检查为空的 PIV 签名槽，不固定覆盖常用 9A/9C。MSG 使用现有 Ed25519 验签，不因硬件类型自动增加管理员或 CA 权限。
+
+目前 ClientState/save_signer 假定可取得 `private_bytes()`。研发时应拆分“签名接口”和“可导出软件密钥存储”：硬件仅提供 public_key、key_id、sign。已有硬件存根却未插设备时须明确失败，不能自动生成软件密钥或重新注册账号。
+
+## 换电脑与存根
+
+卡内使用一个 MSG 专属、经冲突检查的 PIV 数据对象，存储带版本、长度界限和签名的小型账号目录：服务 origin、账号 subject_id、签名槽位、算法、公钥/指纹、可选账号显示名。它是发现线索，不是登录凭据，也不能修改服务端授权。undefined PIV 对象通常无需 PIN 即可读取，所以这里只放可公开的信息，不放 token、PIN、私钥或管理员管理密钥。
+
+新电脑：安装 msgctl → 插入设备 → 读取目录及对应公钥 → 确认服务地址/首次信任 → 本地安全输入 PIN 并按策略触摸 → 设备签署现有 MSG 登录/授权请求 → 服务端核对账号、密钥、撤销状态及当前权限 → 自动生成本机存根。目录签名与设备公钥必须一致；设备序列号只作为查找提示，身份由公钥指纹和签名确认。用户显式填写服务地址可作为目录丢失时的备用发现入口。
+
+本机存根示意（拟定格式）：
+
+```json
+{
+  "version": 1,
+  "signer": {
+    "backend": "yubikey-piv",
+    "slot": "82",
+    "algorithm": "ed25519",
+    "key_id": "k_...",
+    "public_key": "..."
+  },
+  "profiles": [{"server": "https://msg.example", "subject_id": "u_..."}]
+}
+```
+
+存根是可重建的硬件引用，目录 0700、文件 0600；删除电脑配置不会删除设备密钥。证书、服务标识与用户名只是缓存，联网后重新验证，账号改名不改变 subject_id 或 key_id。可能存在的短期 token 属于另一份受保护的会话状态，不与公开存根混写，不复制到其他电脑。
+
+## 硬件签名长度和异步 Agent
+
+Yubico 的 PIV Ed25519 实现把原始 message 交给设备，PC/SC APDU 有长度限制；当前 Yubico Python SDK 对新固件的最大 APDU 约 3062 字节，实际可用 message 还要扣去编码开销。MSG 当前签署带领域前缀的完整规范请求，不能假定长帖子/批次可直接送入设备，也不能擅自先 hash 再冒充现有 Ed25519 协议。
+
+第一阶段建议硬件主钥匙签短小的登录/授权请求；异步 Agent 使用现有短期、范围受限凭据，软件临时签名密钥仅用于确有签名要求的操作。主身份私钥仍不离开设备。授权只给明确服务、操作及 Agent 私有路径；使用独立会话存储和生命周期。完整请求硬件签署只支持验证过的长度，超限明确失败，后续若需统一硬件签署大请求必须单独讨论版本化协议。
+
+插入钥匙不是自动放行：PIN/触摸在本机完成，不进日志、聊天或命令行参数。浏览器先沿用 CLI 批准流程；直接从浏览器访问 PIV 需另行设计本机桥接。拔出设备会阻止新的硬件签名，但不会自动撤销已经授出的浏览器会话或远程短期凭据。
+
+## 恢复和迁移
+
+优先在钥匙内新生成密钥并给同一账号增加硬件 key，保留原账号和权限；不强制导入原私钥。现有 `identity.key_add/key_revoke` 会更新 auth_version，旧会话可能需要重新登录，应在迁移界面说明。删除旧软件主钥匙必须等设备签名、全新电脑登录以及第二条恢复途径都验证后，由用户明确决定。
+
+备用 YubiKey 应生成另一把独立密钥并绑定同一账号。设备内生成的不可导出密钥不能事后复制到备用钥匙；账号恢复依靠预先授权的第二把钥匙或明确的恢复流程。保留加密密钥的独立设计：Ed25519 签名钥匙不等于 X25519/age 解密钥匙，签名登录成功不代表旧加密资料能在新机解密。
+
+## 第一阶段验收
+
+1. 软件签名接口改造不破坏现有身份和 keystore；硬件后端不暴露 private_bytes，不自动降级。
+2. 使用空槽的真实设备验证生成、公钥读取、MSG 原始帧验签、PIN/触摸/超时以及消息长度边界。
+3. 空配置目录的新电脑仅靠钥匙目录和本地授权恢复同一账号；篡改目录、错钥匙、已撤销密钥均拒绝。
+4. 桌面 Linux/Windows/macOS 分别确认 PC/SC、设备锁和热插拔；与现有 OATH/OpenPGP 应用共存。
+5. 主/子 Agent 凭据边界、撤销、短期授权到期以及浏览器登录各自验证，不混称为一项“登录成功”。
+
+## 官方依据
+
+- PIV Ed25519 与固件要求：https://docs.yubico.com/hardware/yubikey/yk-tech-manual/yk5-firmware-5.7.html
+- 设备密钥生成/导入：https://docs.yubico.com/yesdk/users-manual/application-piv/private-keys.html
+- 专属 PIV 数据对象及读取限制：https://docs.yubico.com/yesdk/users-manual/application-piv/get-and-put-data.html
+- PIV Ed25519 原始消息处理：https://github.com/Yubico/yubikey-manager/blob/main/yubikit/piv.py
+- PC/SC APDU 长度约束：https://github.com/Yubico/yubikey-manager/blob/main/yubikit/core/smartcard/__init__.py

{msgctl-0.2.5 → msgctl-0.2.7}/packaging/build-native.py

@@ -178,7 +178,7 @@ license=('MIT')
 provides=('msgctl-server={version}-{release}')
 conflicts=('msgctl-server')
 replaces=('msgctl-server')
-depends=('glibc' 'gcc-libs' 'git' 'openssh' 'postgresql' 'bubblewrap' 'age' 'git-lfs')
+depends=('glibc' 'gcc-libs' 'git' 'openssh' 'postgresql' 'bubblewrap' 'age' 'git-lfs' 'pcsclite')
 options=('!strip' '!debug')
 source=('payload.tar.gz')
 sha256sums=('{checksum}')
@@ -210,7 +210,7 @@ Conflicts: msgctl-server
 Replaces: msgctl-server
 Maintainer: TokenNotIncluded
 Installed-Size: {size}
-Depends: libc6 (>= 2.28), libgcc-s1, git, openssh-server, postgresql, bubblewrap, age, git-lfs, systemd
+Depends: libc6 (>= 2.28), libgcc-s1, git, openssh-server, postgresql, bubblewrap, age, git-lfs, systemd, libpcsclite1
 Description: msg service with independent locked Python runtime
  Configuration and CA initialization are explicit administrator operations.
 """)
@@ -248,7 +248,7 @@ AutoReqProv: no
 Provides: msgctl-server = {version}-{release}
 Conflicts: msgctl-server
 Obsoletes: msgctl-server
-Requires: glibc >= 2.28, libgcc, git, openssh-server, postgresql-server, bubblewrap, age, git-lfs, systemd
+Requires: glibc >= 2.28, libgcc, git, openssh-server, postgresql-server, bubblewrap, age, git-lfs, systemd, libpcsclite.so.1()(64bit)
 %description
 Configuration and CA initialization are explicit administrator operations.
 %prep

{msgctl-0.2.5 → msgctl-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "msgctl"
-version = "0.2.5"
+version = "0.2.7"
 description = "Atomic communication infrastructure for sandboxed agents"
 readme = "README.md"
 requires-python = ">=3.15"
@@ -14,6 +14,7 @@ dependencies = [
     "httpx>=0.28,<1",
     "jsonschema>=4.25,<5",
     "referencing>=0.36,<1",
+    "yubikey-manager>=5.8,<6",
 ]
 
 [[project.authors]]

{msgctl-0.2.5 → msgctl-0.2.7}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "msgctl"
-version = "0.2.5"
+version = "0.2.7"
 description = "Atomic communication infrastructure for sandboxed agents"
 readme = "README.md"
 requires-python = ">=3.15"
@@ -15,6 +15,7 @@ dependencies = [
     "httpx>=0.28,<1",
     "jsonschema>=4.25,<5",
     "referencing>=0.36,<1",
+    "yubikey-manager>=5.8,<6",
 ]
 
 [project.scripts]

{msgctl-0.2.5 → msgctl-0.2.7}/src/msg/__init__.py

@@ -1,3 +1,3 @@
 """Atomic communication for sandboxed agents."""
 
-__version__ = '0.2.5'
+__version__ = '0.2.7'

{msgctl-0.2.5 → msgctl-0.2.7}/src/msg/cli.py

@@ -419,6 +419,9 @@ def parser():
     from msg.client_market import add_commands
 
     add_commands(commands)
+    from msg.client_yubikey import add_commands as add_yubikey_commands
+
+    add_yubikey_commands(commands)
     return cli
 
 
@@ -483,6 +486,10 @@ async def run(args):
             result = await run_command(client, args)
             if args.user and command == 'login':
                 await client.require_username(args.user)
+        elif command == 'yubikey':
+            from msg.client_yubikey import run_command
+
+            result = await run_command(client, args)
         elif command == 'api-key':
             from msg.client_api_keys import run_command
 

{msgctl-0.2.5 → msgctl-0.2.7}/src/msg/client.py

@@ -135,6 +135,7 @@ class ClientState:
                     current.get('subject_id')
                     or current.get('token')
                     or self.paths.file('identity.key').exists()
+                    or self.paths.file('hardware-signer.json').exists()
                     or self.paths.file('oauth-session.json').exists()
                 ):
                     # The per-service identity is already established. A leftover
@@ -150,6 +151,7 @@ class ClientState:
         self.path = self.file('client.json')
         self.key_path = self.file('identity.key')
         self.age_key_path = self.file('encryption.agekey')
+        self.hardware_path = self.file('hardware-signer.json')
         self.pending_path = self.file('registration.json')
         if self.path.exists() or self.path.is_symlink():
             require(
@@ -174,7 +176,15 @@ class ClientState:
         self.data['server'] = self.server
         self.signer = None
         self.encryption_recipient = None
-        if self.key_path.exists() or self.key_path.is_symlink():
+        if self.hardware_path.exists() or self.hardware_path.is_symlink():
+            from msg.client_yubikey import YubiKeySigner
+
+            require(
+                not (self.key_path.exists() or self.key_path.is_symlink()),
+                'client_key_backend_conflict',
+            )
+            self.signer = YubiKeySigner.from_descriptor(private_client_json(self.hardware_path))
+        elif self.key_path.exists() or self.key_path.is_symlink():
             self.signer = private_identity_key(self.key_path)
         if self.age_key_path.exists() or self.age_key_path.is_symlink():
             require(
@@ -227,8 +237,21 @@ class ClientState:
         durable_write(self.path, canonical(self.data), mode=0o600)
 
     def save_signer(self, signer):
-        require(not self.key_path.exists(), 'identity_key_already_exists')
-        durable_write(self.key_path, signer.private_bytes(), mode=0o600)
+        from msg.client_yubikey import YubiKeySigner
+
+        require(
+            not (
+                self.key_path.exists()
+                or self.key_path.is_symlink()
+                or self.hardware_path.exists()
+                or self.hardware_path.is_symlink()
+            ),
+            'identity_key_already_exists',
+        )
+        if isinstance(signer, YubiKeySigner):
+            durable_write(self.hardware_path, canonical(signer.descriptor()), mode=0o600)
+        else:
+            durable_write(self.key_path, signer.private_bytes(), mode=0o600)
         self.signer = signer
 
     def ensure_encryption_key(self):