@mu-cabin/muc-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mu-cabin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,416 @@
+# muc-cli
+
+Terminal client for 东航 MUC IM (the `com.meicloud.im.dh` desktop app, also
+called MUC.app). Drives the same REST surface the desktop talks to, plus the
+binary chat protocol on raw TCP 8101 for sending messages, withdrawing, and
+syncing sessions.
+
+REST commands always coexist with the running desktop and phone — the server
+allows concurrent `accessToken`s. Chat-channel commands share online slots
+with real devices; see [Coexistence](#coexistence) below before sending.
+
+## What it is
+
+A single command (`muc`) packaging:
+
+- **Send** — 1:1 and group text, files, images, and voice clips.
+- **Read** — server-side chat history, profile lookups, group lists, sticker
+  packs, and directory search (people, departments, apps, service numbers).
+- **Manage** — login / token refresh, withdraw a message, clear a session,
+  download a chat-attached file.
+- **Self-describe** — every command has a `--json` mode emitting a stable
+  envelope; `muc manifest --json` returns the full command graph + per-command
+  output JSON Schema for agent / script consumers.
+
+## Install
+
+```bash
+npm i -g @mu-cabin/muc-cli
+muc --version
+```
+
+Requirements: **Node ≥ 18**. macOS, Linux, and Windows are all supported.
+DES-CBC password encryption is `crypto-js` (pure JS) — no
+`--openssl-legacy-provider` flag needed.
+
+`~/.muc/credentials.json` and `~/.muc/config.json` are written with mode
+`600` and the parent dir with mode `700`. POSIX honors that; on Windows the
+modes are silently ignored — protect the files with NTFS ACLs if you're on a
+shared host.
+
+## First-time setup
+
+Before you can `login`, run `muc init` to seed the tenant configuration. The
+CLI is generic across MUC deployments — your MUC admin provides the
+tenant-specific values.
+
+```bash
+muc init       # interactive: walks through APP_KEY, APP_ID, signing secrets, hosts
+```
+
+What `muc init` collects:
+
+| Field | Source | Notes |
+|---|---|---|
+| `appKey` | admin | 8 hex chars |
+| `appId` | admin | 24 hex chars |
+| `signSecretRest` | admin | secret for the regular-API signing scheme |
+| `signSecretSecure` | admin | secret for the `/contacts/secure/...` signing scheme |
+| `pwdDesKey` | admin (optional) | DES-CBC key for password encryption; defaults to `appKey` |
+| `restHost` | default `https://muc.ceair.com/` | press enter to accept |
+| `ssoHost` | default `https://store.ceair.com/` | reserved (advanced) |
+| `imHost` / `imPort` | default `muc.ceair.com` / `8101` | TCP chat channel |
+| `fileHost` / `filePort` | default `muc.ceair.com` / `6101` | TCP file channel |
+
+Built-in defaults are provided **for hosts and ports only** — never for
+`appKey`, `appId`, or signing secrets.
+
+### Non-interactive (CI, scripts)
+
+You can supply values via flags or env vars:
+
+Get the four secrets from your MUC admin first; the snippets below use
+placeholder names — substitute the real values your admin gives you.
+
+```bash
+# Flag form
+muc init --no-interactive \
+  --app-key            "$APP_KEY" \
+  --app-id             "$APP_ID" \
+  --sign-secret-rest   "$SIGN_SECRET_REST" \
+  --sign-secret-secure "$SIGN_SECRET_SECURE" \
+  --json
+
+# Env-var form
+MUC_APP_KEY="$APP_KEY" \
+MUC_APP_ID="$APP_ID" \
+MUC_SIGN_SECRET_REST="$SIGN_SECRET_REST" \
+MUC_SIGN_SECRET_SECURE="$SIGN_SECRET_SECURE" \
+muc init --no-interactive
+```
+
+Environment variables: `MUC_APP_KEY`, `MUC_APP_ID`, `MUC_SIGN_SECRET_REST`,
+`MUC_SIGN_SECRET_SECURE`, `MUC_PWD_DES_KEY`, `MUC_REST_HOST`, `MUC_SSO_HOST`,
+`MUC_IM_HOST`, `MUC_IM_PORT`, `MUC_FILE_HOST`, `MUC_FILE_PORT`.
+
+> **Env-var leakage warning.** Values exported into the environment are
+> visible to other processes on the same machine via `/proc/<pid>/environ`
+> on Linux, and they land in shell history if you don't prefix the command
+> with a space (and `HISTCONTROL=ignorespace` is set). For production setups
+> prefer the **interactive** prompt or **flag-based** invocation — you can
+> protect the flag values with secret-manager retrieval that never touches
+> the env.
+
+### Inspect, repair, reset
+
+```bash
+muc init --check          # validate; exit 0 ok, 6 missing, 7 invalid
+muc init --check --json   # same, machine-readable
+muc init --show           # print config (secrets always redacted)
+muc init --show --json    # JSON envelope — secrets are also redacted here
+                          # (read ~/.muc/config.json directly for raw values)
+muc init --reset --yes    # delete ~/.muc/config.json
+```
+
+Resolution order per field: CLI flag → env var → existing saved value → built-in
+default (hosts/ports only) → interactive prompt (TTY) → fail.
+
+## Login
+
+`muc login` is **non-interactive on the credential side** — it never prompts
+for a password. Pass it via flag, stdin, env var, or `--token-pwd` (reuse
+the saved tokenPwd).
+
+```bash
+# Plaintext flag (avoid; lands in shell history)
+muc login --account WANGLULU8 --password '…'
+
+# Safer: read password from stdin, no flag value
+printf '%s' "$MY_PWD" | muc login --account WANGLULU8 --password-stdin
+
+# Reuse saved tokenPwd (no password needed; ~30 day TTL)
+muc login --token-pwd
+
+# Env-var form
+MUC_ACCOUNT=WANGLULU8 MUC_PASSWORD='…' muc login
+```
+
+- `account` is your MUC uid (uppercase ASCII, e.g. `WANGLULU8`); falls back
+  to `$MUC_ACCOUNT` or the previously-saved uid if `--account` is omitted.
+- One of `--password` / `--password-stdin` / `--token-pwd` / `$MUC_PASSWORD`
+  is required — running `muc login` with no creds fails fast with
+  `AUTH_REQUIRED` (exit 3).
+- The password is encrypted client-side (DES-CBC) before being sent — same
+  scheme the desktop client uses.
+- A successful login saves to `~/.muc/credentials.json` (mode `600`):
+  `accessToken` (≈7 day TTL) and `tokenPwd` (≈30 day TTL, used for silent
+  re-login with `--token-pwd`).
+- A stable per-CLI device id is generated at `~/.muc/device-id` on first
+  run. It is intentionally **different** from the desktop's machine-id so
+  REST sessions stay independent.
+
+## Output contract
+
+- **Default:** human-readable plain text on stdout, errors on stderr in the
+  form `error: <msg>` / `hint: <hint>` / `code: <code> (exit <n>)`.
+- **`--json`** (anywhere on the command line): every command emits a single
+  stable JSON envelope on stdout — `{ok:true, schema_version:1, data}` or
+  `{ok:false, schema_version:1, code, msg, hint?}` — and stderr stays
+  silent. Agents and scripts should always pass `--json`.
+- **Exit codes** are typed and identical in both modes: `0` success, `1`
+  internal bug, `2` usage, `3` auth required / expired, `4` not found, `5`
+  remote / network error, `6` config missing, `7` config invalid.
+- `--help` / `--version` are human escape hatches and bypass the JSON
+  envelope by design. The canonical agent surface is `muc manifest --json`.
+
+## Commands
+
+### Setup
+
+| Command | What it does |
+|---|---|
+| `muc init` | Seed / inspect / reset tenant config (`~/.muc/config.json`). Run before `login`. See [First-time setup](#first-time-setup). |
+
+### REST commands (no impact on the desktop app)
+
+| Command | What it does |
+|---|---|
+| `muc login` | Authenticate, persist `accessToken` + `tokenPwd`. |
+| `muc whoami` | Show the saved profile + token freshness. Local only — does not read tenant config. |
+| `muc search <keyword>` | Org / employee directory search (12 results max, server-side). |
+| `muc search-dept <keyword>` | Department directory search (with employee count + path). |
+| `muc search-app <keyword>` | Search the user's MUC widgets/apps drawer. |
+| `muc search-sno <keyword>` | Search service-numbers (服务号); shows `★` for already-subscribed. |
+| `muc whois <UID>` | Employee info + ext info (`secureApi`). Renders `cn / id / mail / departmentName / positionName / empStatusText`. `--no-ext` skips the slower `getExtInfo` call. |
+| `muc groups` | Starred groups (flat list keyed by `team_id`) + department groups (keyed by `groupId / deptName`). |
+| `muc emoticons` | Sticker packages installed on your account. |
+| `muc history --peer UID \| --team TEAM_ID \| --to-self` | Server-side chat history via the roaming-messages endpoint. Stateless: each call fetches from the server. Default window: 30 days, 50 messages newest-first. |
+| `muc download --file-key <key> [--out <path>]` | Download a chat-attached file from the V5 file server (TCP 6101). **Read-only** — opens a fresh per-request session, no chat login, doesn't kick anyone. Pass `--mid <mid>` instead of `--file-key` plus `--peer/--team/--to-self` to look the file up via roaming history. Verifies md5 on completion. |
+| `muc manifest` | Print the full command graph + per-command output JSON Schema. Pair with `--json` for agents. |
+
+`history` flags: scope with one of `--peer UID`, `--team TEAM_ID`,
+`--sid <UID1|UID2 or teamId>`, or `--to-self`. `--limit N` (default 50),
+`--days N` (window from now, default 30), `--before <ts|ISO>` to fetch
+older than a moment, `--sub-type N` to filter to one type (e.g. `1` text,
+`7` file, `8` image), `--desc` for newest-first (default: oldest at top).
+The fetched `timestamp` is normalized to ms.
+
+```bash
+muc history --peer YANWENYU --limit 100
+muc history --to-self --days 7
+muc history --team 9009876543210000 --before 2026-04-20 --json | jq .
+```
+
+### Chat-channel commands (TCP 8101) — see [Coexistence](#coexistence)
+
+| Command | What it does |
+|---|---|
+| `muc tcp-ping [--wait N] [--debug]` | TCP connect + NEGOTIATE only. Smoke test, no login frame, **zero** kick risk. |
+| `muc sync [--os OS]` | After chat-login, run `syncDone` / `syncSession` / `syncWithdraws`. Read-only. |
+| `muc search-team <keyword> [--enrich]` | Search groups you belong to via the chat channel; `--enrich` follows up with `team/get_team` per id to print names + member counts. |
+| `muc send (--to-self \| --peer UID \| --team TEAM_ID) <text> [--yes-not-self]` | Send a plain-text message. **Visible to the recipient.** |
+| `muc send-file <file> [target] [--yes-not-self]` | Upload a file (TCP 6101) and broadcast as `MESSAGE_CHAT_FILE` (subType=7). Returns persistent `fileKey` + `mid`. **Visible.** Uses both 6101 (upload) and 8101 (broadcast) — costs the chosen `--os` slot for the broadcast. |
+| `muc send-image <file> [target] [--width N --height N]` | Same as `send-file` but as `MESSAGE_CHAT_IMAGE` (subType=8). Width/height auto-probed from PNG/JPEG/GIF/BMP headers; pass `--width/--height` to override. |
+| `muc send-voice <file> --duration <ms> [target]` | Same as `send-file` but as `MESSAGE_CHAT_AUDIO` (subType=9). `--duration <ms>` is required (the desktop renders the bubble's clip length from this metadata, not from the file). |
+| `muc withdraw --mid <MID> [target]` | Recall a sent message. Original gets replaced server-side with "您撤回了一条消息". Target flag must match the original message's chat. |
+| `muc clear-session [target]` | Delete a session from your client-side history (syncs to all your devices). **Doesn't delete server-side history** — `history` still returns the messages. |
+
+`--os` defaults to `iOS`. Valid values: `Windows`, `OS X`, `Mac`, `iOS`,
+`Android`. **`--os` does not provide coexistence — read the section below
+before using any chat-channel command if you have a real device logged in.**
+
+Sending to anyone other than yourself requires the explicit `--yes-not-self`
+flag — a guard against accidentally messaging real humans during testing.
+
+```bash
+muc tcp-ping --wait 8                         # safe protocol smoke test
+muc send "hello from the CLI"                 # to-self (default)
+muc send --peer ZHANG_W2 "ping" --yes-not-self
+muc send --team 9009876543210000 "team message" --yes-not-self
+
+muc send-file ./report.pdf --to-self                                  # self test
+muc send-image ./screenshot.png --peer ZHANG_W2 --yes-not-self        # auto width/height
+muc send-voice ./clip.amr --duration 3500 --to-self                   # 3.5 s clip
+
+muc download --file-key /chat/m/WANGLULU8/.../<md5> --out ./got.bin   # by explicit key
+muc download --mid 69ef1ae07e5462c465c05e00 --to-self                 # look up body via roaming
+muc download --mid <MID> --peer YANWENYU --out ./inbox/                # save into a directory
+```
+
+`download` is the only file-channel command that **doesn't** open a chat
+session — it speaks only port 6101 (and a one-time bucket lookup on first
+call). Run it from any environment without disturbing your desktop or phone.
+
+## Coexistence
+
+**REST commands always coexist** with a running desktop and phone — the
+server allows concurrent `accessToken`s. `whoami`, `search`, `search-dept`,
+`search-app`, `search-sno`, `history`, `whois`, `groups`, `emoticons`, and
+`download` are REST-only (or 6101-only, in `download`'s case) and safe to
+run anytime.
+
+**Chat-channel commands** (`sync`, `search-team`, `send`, `send-file`,
+`send-image`, `send-voice`, `withdraw`, `clear-session`) open a TCP-8101
+session and share a per-user **two-slot** model with real devices:
+
+| Slot | `--os` values |
+|---|---|
+| PC | `Windows`, `"OS X"`, `Mac` |
+| Mobile | `iOS` (default), `Android` |
+
+A second login in the same slot kicks the previous client off the realtime
+channel — the IM panel goes offline, but tokens stay valid (reopen to
+recover). The Mac desktop signs in as `"OS X"` (PC slot); the iPhone signs
+in as `iOS` (Mobile slot).
+
+The CLI defaults to `--os iOS` so it coexists with a Mac desktop. If your
+iPhone is also signed in, both slots are taken and any TCP command will
+kick one of them — fall back to REST-only commands.
+
+`tcp-ping` only does TCP connect + NEGOTIATE (no `auth/login`), so it can't
+kick anything. Run it first to confirm the wire protocol is happy on your
+network.
+
+If you do get kicked, reopen the desktop's IM panel or relaunch the mobile
+app to recover — tokens stay valid.
+
+## Examples
+
+```bash
+$ printf '%s' "$MY_PWD" | muc login --account WANGLULU8 --password-stdin
+uid: WANGLULU8
+empId: 5394483846707200
+name: 王璐璐
+accessToken: TV5l…u9kQ (redacted; use --json for raw)
+accessTokenExpireAt: 1745678340000
+tokenPwdRefreshed: true
+tokenPwdExpireAt: 1748097540000
+
+$ muc whoami
+uid: WANGLULU8
+empId: 5394483846707200
+name: 王璐璐
+deviceId: 8e413b4141…
+deviceName: WANGLULU8-mbp.local (muc-cli)
+accessToken: TV5l…u9kQ (redacted; use --json for raw)
+accessTokenExpireAt: 1745678340000
+tokenPwdSet: true
+tokenPwdExpireAt: 1748097540000
+savedAt: 1745073540000
+credentialsPath: ~/.muc/credentials.json
+
+$ muc search 张
+ZHANG_W2       张伟      飞行部 / 机长室
+ZHANGSAN03     张三      地面服务部
+…
+
+$ muc whois ZHANG_W2
+uid        ZHANG_W2
+name       张伟
+empId      4892173049281024
+mobile     1380013…
+email      zhang.wei@ceair.com
+dept       飞行部 / 机长室
+title      机长
+
+$ muc groups
+starred:
+  [常用] (3)
+    9001234567890123     IT 值班群
+    9001234567890124     运行联络
+    9001234567890125     部门通知
+dept groups: 1
+  9009876543210000     飞行部 / 机长室
+
+$ muc emoticons
+1001             默认表情包  (32)
+1042             航空主题     (18)
+```
+
+## Files & paths
+
+| Path | Purpose | Mode |
+|---|---|---|
+| `~/.muc/config.json` | tenant config: APP_KEY, APP_ID, signing secrets, hosts/ports | 600 |
+| `~/.muc/credentials.json` | accessToken, tokenPwd, profile | 600 |
+| `~/.muc/device-id` | stable per-CLI deviceId (sha256 hex) | 600 |
+
+Both files share the `~/.muc/` parent (mode 700). The CLI creates them on
+first use; you should never need to edit them by hand.
+
+## What it can't do (yet)
+
+- **Richtext messages** (`subType=11`, mixed text + image + @-mention in one
+  bubble). The image segments share the file-channel upload path so the
+  bulk of the work is already there; just needs a body-builder + a
+  `send-rich` command.
+- **Forwarded / merged messages** (`subType=26`).
+- **SSO / scan-to-login.** REST username+password works; the SSO flow is
+  not wired up.
+- **Live push streaming.** Use `muc history` for server-side message
+  retrieval; there is no long-lived `talk/msg` listener wired up.
+- **Image thumbnails.** The upload step asks the server to make `tn1`/`tn5`
+  thumbs, but `muc download` only fetches the original `fileKey`.
+- **End-to-end-encrypted file content.** Not active on the default tenant
+  and the CLI doesn't implement it.
+
+## Troubleshooting
+
+- `code: CONFIG_MISSING` (exit 6) — `~/.muc/config.json` is absent. Run
+  `muc init` to create it. The CLI cannot guess your tenant's signing
+  secrets.
+- `code: CONFIG_INVALID` (exit 7) — the file exists but failed schema
+  validation (corruption, manual edit gone wrong, or a stale schema after
+  upgrade). Run `muc init` to repair it; `--reset --yes` to start clean.
+- `login failed: code=…` — sign or DES is wrong. Double-check the signing
+  secrets and `appKey` / `appId` you supplied to `muc init` against the
+  values your MUC admin provided. `muc init --show` (secrets redacted) lets
+  you confirm what's currently saved; `muc init` (interactive) lets you
+  re-enter the values.
+- `error: not logged in` (exit 3, code `AUTH_REQUIRED`) — the saved
+  credentials file is missing or unreadable. Check `~/.muc/credentials.json`
+  and re-run `muc login`.
+- `code: AUTH_EXPIRED` (exit 3) — accessToken or tokenPwd was rejected by
+  the server. Re-run `muc login --token-pwd` (or full `muc login` if
+  `tokenPwd` is also stale).
+- `EPROTO` / TLS errors — corporate proxy or VPN intercepting traffic.
+  `muc-cli` does not pin certificates, so adding the proxy CA to your Node
+  trust store should suffice (`NODE_EXTRA_CA_CERTS=/path/to/ca.pem`).
+- A TCP send kicks your desktop off the IM panel — the CLI's `--os` value
+  collided with the desktop's slot. See [Coexistence](#coexistence) above:
+  default `--os iOS` only risks the Mobile slot (your iPhone), not the
+  desktop. If both desktop and phone are online, drop to REST-only
+  commands.
+
+### Exit-code summary
+
+| Exit | Code |
+|---|---|
+| 0 | success |
+| 1 | INTERNAL |
+| 2 | USAGE |
+| 3 | AUTH_REQUIRED, AUTH_EXPIRED |
+| 4 | NOT_FOUND |
+| 5 | REMOTE_ERROR, NETWORK |
+| 6 | CONFIG_MISSING |
+| 7 | CONFIG_INVALID |
+
+## Security
+
+- Both files in `~/.muc/` are written with mode `600`. **Don't** check them
+  into git or copy them to shared machines.
+- **Don't share `~/.muc/config.json`** — it contains your tenant's signing
+  secrets (`signSecretRest`, `signSecretSecure`, `pwdDesKey`, `appKey`).
+  Anyone with these can impersonate API calls against your MUC tenant.
+- `MUC_PASSWORD` ends up in shell history; prefer `--password-stdin` or
+  `--token-pwd` for refreshes.
+- **Prefer interactive `muc init` over env vars.** Environment variables
+  leak through shell history and `/proc/<pid>/environ` to other processes
+  on the same machine. Use the interactive prompt or one-shot flags pulled
+  from a secret manager rather than persistent `MUC_*` exports.
+- TCP login over 8101 registers a device session in one of two slots per
+  user (PC or Mobile). A second login in the same slot kicks the first.
+  Default `--os iOS` keeps the CLI on the Mobile slot; only your iPhone is
+  ever at risk.
+- `tcp-ping` is the only chat-channel command that cannot kick anything —
+  use it as a network smoke-test before trying TCP sends.