msgctl 0.2.6__tar.gz → 0.2.8__tar.gz

{msgctl-0.2.6 → msgctl-0.2.8}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 变更记录
 
+## 0.2.8
+
+- Normalize software and YubiKey accounts under shared XDG service/account paths.
+- Add `--account`, `account list`, `account use` and safe portable account imports.
+- Preserve old singleton identities, nested local-agent databases and listener cursors during migration; reject conflicting credentials without removing their source.
+
+
+## 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 内置插件仍处于方案讨论阶段，本版本不实现或启用该功能。

{msgctl-0.2.6 → msgctl-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msgctl
-Version: 0.2.6
+Version: 0.2.8
 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.5**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.5` 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.7**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.7` 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,9 @@ 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.5](https://pypi.org/project/msgctl/0.2.5/) is published on PyPI. The public service runs native `msgd 0.2.5-20261001.17` from source `143dd30`; 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.7](https://pypi.org/project/msgctl/0.2.7/) is published on PyPI and [GitHub](https://github.com/TokenNotIncluded/msg/releases/tag/v0.2.7). The public service runs native `msgd 0.2.7-20261002.19` from source `6dc67e5`; 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.
+
+Local account selection uses one layout for software and YubiKey signers. Starting with 0.2.8, use `msg --account light identity show`, `msg account list`, and `msg account use light`; account data lives under `msg/services/<domain>/accounts/<account>` in the respective XDG directories. Stop old listeners before migration. See [accounts and filesystem layout](docs/FILESYSTEM_LAYOUT.md).
 
 ## Development and builds
 
@@ -245,3 +248,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.6 → msgctl-0.2.8}/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.5**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.5` 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.7**. For the latest client, use `uv tool install --python 3.15 --force msgctl==0.2.7` 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,9 @@ 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.5](https://pypi.org/project/msgctl/0.2.5/) is published on PyPI. The public service runs native `msgd 0.2.5-20261001.17` from source `143dd30`; 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.7](https://pypi.org/project/msgctl/0.2.7/) is published on PyPI and [GitHub](https://github.com/TokenNotIncluded/msg/releases/tag/v0.2.7). The public service runs native `msgd 0.2.7-20261002.19` from source `6dc67e5`; 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.
+
+Local account selection uses one layout for software and YubiKey signers. Starting with 0.2.8, use `msg --account light identity show`, `msg account list`, and `msg account use light`; account data lives under `msg/services/<domain>/accounts/<account>` in the respective XDG directories. Stop old listeners before migration. See [accounts and filesystem layout](docs/FILESYSTEM_LAYOUT.md).
 
 ## Development and builds
 
@@ -215,3 +217,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.6 → msgctl-0.2.8}/docs/CLIENT_CONNECTIONS.md

@@ -33,7 +33,7 @@ Host *
     Transport http
 ```
 
-Then connect with `msg production ""`, `msg production "identity show"`, or `msg alice@lab "identity show"`. Host aliases resolving to the same service origin use the same identity. Use `msg -F /path/to/config production "identity show"` to select another configuration file.
+Then connect with `msg production ""`, `msg production "identity show"`, or `msg alice@lab "identity show"`. Host aliases resolving to the same service origin share the same account selection; `--account NAME` selects a different local account. Use `msg -F /path/to/config production "identity show"` to select another configuration file.
 
 | Directive | Meaning |
 | --- | --- |
@@ -52,21 +52,21 @@ The file must be owned by the invoking user and must not be group/world writable
 
 ## Identity and path binding
 
-Every canonical service origin has one identity under the standard XDG bases:
+Each canonical service origin has independently stored accounts under the standard XDG bases. For local account `alice`:
 
 ```text
-~/.config/msg/services/own.example.org/
-~/.local/share/msg/services/own.example.org/identity.key
-~/.local/share/msg/services/own.example.org/encryption.agekey
-~/.local/state/msg/services/own.example.org/client.json
-~/.cache/msg/services/own.example.org/
+~/.config/msg/services/own.example.org/accounts/alice/
+~/.local/share/msg/services/own.example.org/accounts/alice/identity.key
+~/.local/share/msg/services/own.example.org/accounts/alice/encryption.agekey
+~/.local/state/msg/services/own.example.org/accounts/alice/client.json
+~/.cache/msg/services/own.example.org/accounts/alice/
 ```
 
 HTTPS hostnames are lowercased and international names use IDNA. Default port 443 and a trailing slash do not create a second identity. Nondefault ports add `~PORT`; HTTP adds `http~`; IPv6 uses a fixed hexadecimal address component. Very long names use a bounded readable prefix and the full SHA-256 of the canonical origin. Paths never contain raw URL credentials, queries or resource paths.
 
-The first connection has no hardcoded public-domain fallback. Choose a destination, `--server`, or `MSG_SERVER`. Subsequent ordinary commands can reuse the saved service selection. Named `--profile` entries are service aliases rather than separate identities. Switching domains isolates keys, session tokens, certificates, pending journals and operation caches. Signed requests and certificates remain bound to their target service.
+The first connection has no hardcoded public-domain fallback. Choose a destination, `--server`, or `MSG_SERVER`. Subsequent ordinary commands can reuse the saved service selection. Named `--profile` entries are service aliases rather than accounts. Use `msg account list`, `msg account use alice`, or the invocation-only `--account alice` selector. Switching domains isolates keys, session tokens, certificates, pending journals and operation caches. Signed requests and certificates remain bound to their target service.
 
-Existing profiles migrate only to their recorded service. Migration detects destination conflicts before moving any file and preserves resumable operations. If two old profiles contain different identities for the same domain, migration stops with `client_migration_conflict`; neither identity is discarded. Explicit legacy `--config-dir` remains a portable, origin-bound compatibility option. See [filesystem layout](FILESYSTEM_LAYOUT.md).
+Existing profiles migrate only to their recorded service. Migration detects destination conflicts before moving any file and preserves resumable operations. Import old profiles for the same domain under different account labels. Importing different credentials into an occupied account stops with `client_migration_conflict`; neither identity is discarded. Explicit legacy `--config-dir` remains a portable, origin-bound compatibility option. See [filesystem layout](FILESYSTEM_LAYOUT.md).
 
 The historical `msg.lmm.best/v1/` signature prefix is a fixed protocol framing identifier, not a hostname or network destination. Changing that prefix would invalidate existing signatures. Repository links likewise identify the source project, not a required deployment domain.
 

{msgctl-0.2.6 → msgctl-0.2.8}/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.
 
@@ -18,7 +18,7 @@ msg alice@own.example.org ""
 msg alice@own.example.org 'post /main --text "Hello"'
 ```
 
-Each service domain selects one identity and its XDG data/state/cache directories. The username must match the authenticated account. Configure aliases in `~/.config/msg/config`; see [connections](CLIENT_CONNECTIONS.md) and [filesystem layout](FILESYSTEM_LAYOUT.md). Existing `--server`, `--profile` service aliases and origin-bound portable `--config-dir` directories remain supported.
+Each service domain has a default account and separate XDG data/state/cache directories for each local account; select another with `--account NAME` or `msg account use NAME`. The username must match the authenticated account. Configure aliases in `~/.config/msg/config`; see [connections](CLIENT_CONNECTIONS.md) and [filesystem layout](FILESYSTEM_LAYOUT.md). Existing `--server`, `--profile` service aliases and origin-bound portable `--config-dir` directories remain supported.
 
 ## Shared protocol ownership
 
@@ -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.6 → msgctl-0.2.8}/docs/FILESYSTEM_LAYOUT.md

@@ -4,18 +4,34 @@ Host filesystem paths follow the [XDG Base Directory specification](https://spec
 
 ## Client
 
-`src/msg/paths.py` owns layout selection and private directory validation. Empty or relative XDG base variables use the standard defaults. Normal client paths append `msg/services/<canonical-domain>` to each base directory. One service origin has one identity; `--profile NAME` stores only a service-selection alias in configuration. Alias names allow letters, digits, underscores and hyphens, up to 64 characters. Choose an initial destination, `--server`, or `MSG_SERVER`; there is no hardcoded public service. See [connection configuration](CLIENT_CONNECTIONS.md) for SSH-style destinations and `Host` entries.
+`src/msg/paths.py` owns layout selection and private directory validation. Empty or relative XDG base variables use the standard defaults. Normal client paths append `msg/services/<canonical-domain>/accounts/<account>` to each base directory. An account is a local label shared by software and hardware signers; it is not a hardware type or permission. `--account NAME` selects one identity for this invocation; `msg account use NAME` selects the default for that service. `--profile NAME` remains a service-selection alias. Alias names allow letters, digits, underscores and hyphens, up to 64 characters. Choose an initial destination, `--server`, or `MSG_SERVER`; there is no hardcoded public service. See [connection configuration](CLIENT_CONNECTIONS.md) for SSH-style destinations and `Host` entries.
 
 | Purpose | Default directory | Contents |
 | --- | --- | --- |
-| Configuration | `~/.config/msg` | SSH-style `config`, service-selection aliases and per-service configuration; never new private keys or tokens |
-| Durable identity data | `~/.local/share/msg/services/<domain>` | Signing keys, encryption keys including rotated keys, CA keys, exported certificates, Bank approval records, retained custodial recovery history |
-| Persistent state | `~/.local/state/msg/services/<domain>` | `client.json` (server binding, tokens and certificate IDs), registration and operation journals, OAuth sessions, upgrade locks |
-| Disposable cache | `~/.cache/msg/services/<domain>` | Verified operation catalogs |
+| Configuration | `~/.config/msg` | SSH-style `config`, service-selection aliases and per-service configuration; per-account configuration and `services/<domain>/current-account.json`; never new private keys or tokens |
+| Durable identity data | `~/.local/share/msg/services/<domain>/accounts/<account>` | Signing keys, encryption keys including rotated keys, CA keys, exported certificates, Bank approval records, retained custodial recovery history |
+| Persistent state | `~/.local/state/msg/services/<domain>/accounts/<account>` | `client.json` (server binding, tokens and certificate IDs), registration and operation journals, OAuth sessions, upgrade locks |
+| Disposable cache | `~/.cache/msg/services/<domain>/accounts/<account>` | Verified operation catalogs |
 | Temporary work | `$XDG_RUNTIME_DIR/msg`, or Python's temporary directory | Unique private working directories, removed when the operation exits; Python honors `TMPDIR`, `TEMP`, and `TMP` |
 
 Application directories are owned by the invoking user and mode `0700`; credentials and session files are `0600`. Symlinked application directories are rejected before changing permissions. Generic XDG base directories are never chmodded by the client. A configured runtime directory must already be owned by the user and private. Do not put a profile in a shared directory.
 
+## Accounts
+
+```sh
+msg --server https://msg.lmm.best account list
+msg --server https://msg.lmm.best account use light
+msg --server https://msg.lmm.best --account light identity show
+msg --server https://msg.lmm.best --account light auth approve CODE
+msg --server https://msg.lmm.best account import light /path/to/old-portable-directory
+```
+
+Local names allow letters, digits, underscores, dots and hyphens, begin with a letter or digit, and are at most 64 characters. They need not equal the public handle and remain stable after a handle rename. No account is selected by whether its signer is hardware or software. Selection never exports a key, contacts a server or touches a YubiKey. The public handle is still checked when `user@host` is supplied; use `--account` to select the saved identity explicitly.
+
+The service default is stored in `~/.config/msg/services/<domain>/current-account.json`. An invocation override does not change it. If no account has been selected, an old per-service identity migrates under its existing handle, or `default` when no handle is known. A fresh service also starts with local label `default`; specify `--account NAME` when creating additional identities. Existing `hardware-signer.json` is account state, not a private key. Its path is `~/.local/state/msg/services/<domain>/accounts/<account>/hardware-signer.json`.
+
+Stop old clients and background listeners before upgrading or migrating. Migration preserves local subagent databases and listener cursors as well as signing keys, encryption keys, tokens and journals; regenerable caches can be rebuilt. Destination conflicts and unsafe files stop before source files are removed. A portable directory, or the old standard per-service data/state directory, can be imported with `account import`; split data/state are moved together. No `msg-hardware` namespace is used.
+
 Stop clients using the old profile before migrating:
 
 ```sh
@@ -23,7 +39,7 @@ msg --server https://msg.lmm.best --profile lightjunction --migrate-from ~/.conf
 msg --profile lightjunction tui
 ```
 
-Migration checks every source file and every destination conflict before writing. It preserves keys and resumable journals, writes copies durably, verifies them, and only then removes original files. Identical copies from an interrupted migration are accepted; different credentials are never overwritten. Legacy catalog caches and nested profile containers remain in place and can be removed separately after migration. Legacy single-directory and split XDG profiles migrate to their recorded service on first use. A migration explicitly targeting a different service stops before creating destination files. Split-profile keys and state are copied and checked together; distinct identities for the same domain are never merged or overwritten. Explicit `--config-dir DIRECTORY` retains the old portable single-directory layout for existing integrations; it cannot be combined with `--profile` or `--migrate-from`.
+Migration checks every source file and every destination conflict before writing. It preserves keys and resumable journals, writes copies durably, verifies them, and only then removes original files. Identical copies from an interrupted migration are accepted; different credentials are never overwritten. Legacy catalog caches and nested profile containers remain in place and can be removed separately after migration. Legacy single-directory and split XDG profiles migrate to their recorded service on first use. A migration explicitly targeting a different service stops before creating destination files. Split-profile keys and state are copied and checked together; distinct identities use distinct account labels and are never merged or overwritten. Explicit `--config-dir DIRECTORY` retains the old portable single-directory layout for existing integrations; it cannot be combined with `--profile` or `--migrate-from`.
 
 ## Service
 

msgctl-0.2.8/docs/YUBIKEY.md

@@ -0,0 +1,73 @@
+# 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 `--account NAME` to select an account on the same service; software and YubiKey signers use the same XDG layout. Inspect a candidate slot first. `82` is the default, but this case uses `83` because `82` already contains an unrelated key.
+
+```sh
+msg --account light --server https://msg.lmm.best yubikey init --slot 83
+msg --account light --server https://msg.lmm.best identity new light
+msg --account 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.
+
+## Select an account or move to another computer
+
+```sh
+msg --server https://msg.lmm.best account list
+msg --server https://msg.lmm.best account use light
+# On another computer, install the client/PCSC, insert the same key, then:
+msg --account light --server https://msg.lmm.best yubikey login --slot 83
+# Approve a browser login using the chosen identity:
+msg --account light --server https://msg.lmm.best auth approve CODE
+```
+
+Do not run `init` or register again when moving computers. The public hardware reference and account state are recreated under `msg/services/msg.lmm.best/accounts/light` in their respective XDG roots. A legacy portable directory can be moved with `msg --server https://msg.lmm.best account import light /path/to/old-directory`; stop its background clients first.
+
+`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.8/docs/YUBIKEY_CASE.md

@@ -0,0 +1,37 @@
+# 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](https://pypi.org/project/msgctl/0.2.7/) 已发布；线上部署为 `msgd 0.2.7-20261002.19`，源码 `6dc67e5`。本案例已[发布到 X](https://x.com/LIghtJUNction_x/status/2105704085248946334)，通过 Chrome 扩展操作并回读确认正文。

{msgctl-0.2.6 → msgctl-0.2.8}/docs/YUBIKEY_DESIGN.md

@@ -1,6 +1,6 @@
 # 内置 YubiKey 插件方案草案
 
-状态：仅研究，尚未实现。本次不生成、导入、覆盖或删除设备/电脑上的任何密钥。
+状态：第一阶段已实现于 msgctl 0.2.7；当前行为和验收边界见 [YubiKey 使用说明](YUBIKEY.md)。以下保留原设计方向，完整异步写入授权仍待研发。
 
 ## 推荐方向
 

{msgctl-0.2.6 → msgctl-0.2.8}/docs/post-universe.md

@@ -80,3 +80,85 @@ Tests cover anonymous projections, hidden ancestors, hidden reply targets, curso
 binding/pagination, authenticated private views, wrong-subject rejection, exact
 CSP pins and cross-language browser signatures against the real executor. Browser
 fixtures are explicitly synthetic and exist only in the verification script.
+
+## Token field refinement (local changes, 2026-10-01)
+
+The stage is neutral black, not blue; the scenery is a folded, deterministic
+field of small monochrome token glyphs, not a simulated galaxy or extra accounts.
+A new layout version places the real `u_root` at the origin and keeps an inner
+clearance around it. Coordinates are visual, not a protocol or stored identity
+attribute. Colors belong to identities, not to the background.
+
+Independent visual channels prevent money, presence and authority being confused:
+
+- Root: white geometric core, layered corona and radial rays; always prominent,
+  never an assertion that the administrator is currently online. Identification
+  uses the reserved subject ID, never a display name or user-controlled role.
+- Certificate: a 1.37× body, quiet colored crystal, hexagonal seal and diamond
+  badge. A current publicly readable certificate must pass the existing complete
+  chain validator, including expiry, issuer/key revocation and scope validity.
+  This is a scoped authority marker, not a reputation rating. All unverified,
+  hidden or expired observations fail closed, without a badge.
+- Activity: brightness follows valid, explicitly self-reported presence. On TTL
+  expiry it immediately stops claiming presence; a recent **public post** can
+  provide a weaker, smoothly decaying glow. Missing presence means unknown, not
+  offline. No login history, private posts or messages affect public brightness.
+- Reserve: a thin segmented lower arc uses `log10(1 + units)`, capped in size.
+  Exact amounts use integer minor units encoded as decimal strings (including
+  int64 values above JavaScript's safe integer range), and the configured
+  currency code and scale. Money never enlarges the body. Undisclosed, unavailable
+  and zero values remain distinct in the inspector.
+
+`discovery.get` and the existing flat user read query accept an explicit `star`
+field; default responses are unchanged. It is an anonymous-only projection so a
+privileged reader cannot accidentally populate a shared graph with private facts.
+Each subject summary scans at most 32 candidate certificates and 64 recent post
+candidates, checks current access and the execution deadline, and whitelists
+presence fields. No presence message, capability hint or hidden certificate path
+is included. A bounded scan without an observation is not proof of inactivity.
+
+`/_universe?kind=users` requests that field; the initial page also returns a
+separately authorized root `anchor`, even if root sorts beyond the loaded page.
+`/_universe?ids=u_...,...` refreshes up to 100 unique user IDs, with at most four
+concurrent executor reads. It cannot be combined with a cursor or author filter.
+Every response is still read-only, no-store, and uses anonymous authority. Page
+cursors issued for the earlier, smaller projection must be restarted on upgrade.
+
+Visible public scenes refresh loaded identities every 30 seconds. An observation
+older than 90 seconds stops supporting a certificate, presence or balance display;
+expired certificates and presence stop immediately, even in paused scenes. The
+server's observation time prevents a skewed device clock from inventing status.
+A user that becomes unreadable disappears on the next successful refresh. This
+is a bounded-freshness visualization, not a real-time revocation guarantee.
+
+The reserve publication policy is shared with `money.public_balance`: root and
+active banks have mandatory public balances, others require an explicit opt-in.
+`/_universe/me` reads the current session owner's `money.balance`, requires both
+envelope and data subject to match, and returns a **self-only** reserve. A read
+failure is unavailable, never a zero. This private value lives only in My orbit
+and is removed when switching or hiding the page. It cannot influence the public
+scene, search, counts, arc geometry or any other account's display.
+
+Intro copy and the mission widget fade after real pointer movement, clicking,
+scrolling or keyboard interaction. They become inert/hidden to accessibility APIs
+and do not reappear during the visit. `?` and the help button reopen the field
+legend and current expedition progress. Reduced motion removes the fade and
+ambient movement. Selected mobile stars are framed above the inspector; software
+Canvas projects the same certificate seals, balance arcs and root geometry.
+
+### Local validation
+
+```
+node --test tests/js/nebula.test.cjs
+python scripts/check_nebula_browser.py
+uv run pytest tests/test_star_projection.py tests/test_universe.py \
+  tests/test_presence_claim.py tests/test_money_public.py
+```
+
+The browser script uses isolated fixtures only. `MSG_BROWSER_PATH` selects an
+installed Chromium. Restricted environments can explicitly select
+`MSG_NEBULA_OFFLINE_DOM=1` and `MSG_NEBULA_EXPECT_RENDERER=canvas-3d`; this tests
+actual scene/UI code and the inline script pin without navigation. It **does not**
+validate the HTTP response sandbox, real sessions, the database, WebCrypto writes,
+or WebGL. No browser policy is disabled. PostgreSQL, Python 3.15 and the pinned
+project dependencies remain necessary for full backend acceptance.

{msgctl-0.2.6 → msgctl-0.2.8}/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.6 → msgctl-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "msgctl"
-version = "0.2.6"
+version = "0.2.8"
 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.6 → msgctl-0.2.8}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "msgctl"
-version = "0.2.6"
+version = "0.2.8"
 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]