bofile 0.1.0__tar.gz

bofile-0.1.0/LICENSE

@@ -0,0 +1,6 @@
+All rights reserved.
+
+This package is distributed as proprietary BoFile software. Publication of the
+Python source or wheel does not grant an open-source license or transfer
+ownership of the BoFile name or software. Separate written permission is
+required for redistribution, sublicensing, or commercial incorporation.

bofile-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include tests *.py

bofile-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: bofile
+Version: 0.1.0
+Summary: Standard-library CLI for the local BoFileX HTTP API
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://bofile.com/
+Project-URL: Documentation, https://bofile.com/install.html
+Keywords: bofile,bofilex,cli,file-transfer
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: File Sharing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bofile — Python CLI for BoFileX
+
+Control a **running local BoFileX** using its existing HTTP API. The PyPI
+distribution, Python module and console command are all named `bofile`.
+Python 3.10+; **no runtime dependencies**. This package does not include the
+BoFileX daemon or implement libp2p, start services, or create machine state.
+
+## Install and run
+
+After publication:
+
+```sh
+python -m pip install bofile
+bofile --help
+python -m bofile --version
+```
+
+From this directory during development:
+
+```sh
+python -m pip install -e .
+python -m bofile --help
+```
+
+The default API origin is `http://127.0.0.1:34120`, set by
+`client/bofilex_main.go`. BoFileX can choose another free port if that port is
+busy: use the actual HTTP UI origin explicitly. A native-only Wails window may
+not expose this HTTP API. The old dialer API on port 34115 is a different API
+and is not supported here.
+
+```sh
+bofile --base-url http://127.0.0.1:34120 info
+bofile peers --json
+bofile message send PEER_ID "你好，文件已经准备好了"
+bofile files list PEER_ID . --json
+bofile transfer upload PEER_ID ./report.pdf /shared
+bofile transfer download PEER_ID /shared/report.pdf ./downloads --size 12345 --mtime 1700000000
+bofile transfer list --json
+bofile transfer cancel 42
+bofile transfer resume 42
+bofile channels list PEER_ID
+bofile channels select nat --direction up
+bofile channels select auto
+bofile channels mode direct
+bofile channels mode auto
+```
+
+Replace `PEER_ID` with a full peer ID from `peers`. Global flags (`--base-url`,
+`--token-file`, `--timeout`, `--json`) work before or after subcommands.
+Each command supports `--help`. This CLI defaults to a 30-second HTTP timeout.
+There is no automatic retry, since resubmitting a mutation could duplicate work.
+
+## Authentication and connection safety
+
+`core/modules/admin/guard.go` allows non-browser scripts that omit Origin,
+Referer and Sec-Fetch-Site. The CLI uses that contract by default and **does not
+read any token, configuration, identity or state file automatically**.
+It never fetches the UI page to harvest a session cookie.
+
+When a persisted UI token is needed, explicitly select the existing file:
+
+```sh
+bofile --token-file /path/to/ui-session.token info
+```
+
+The file must contain the 32-character hex UI token. It is sent as the cookie
+`bofile_ui_<API-port>`, not as a Bearer token or query parameter. No token option
+accepts the raw secret on the command line. The file is read only and is never
+created or refreshed. Invalid/missing explicit files fail rather than falling
+back silently. A 401/403 is an error; remote management password login is not
+implemented.
+
+BoFileX resolves its own state using `BOFILE_STATE_DIR`, or on Windows usually
+`%ProgramData%\bofilex`, otherwise the platform user config directory with the
+`bofilex` namespace (and native fallback rules). Choose the file used by your
+instance explicitly; this CLI does not reproduce the daemon's state migration
+or executable-directory fallback logic.
+
+Only **numeric loopback origins** are accepted (`127.0.0.1`, `[::1]`); DNS names,
+including `localhost`, non-loopback IPs, URL credentials, base paths, queries and
+fragments are rejected before reading a token. Environment HTTP proxies are
+disabled. All redirects are refused, even to another loopback port. This keeps
+cookies and local data from being forwarded to a different endpoint or through
+a proxy. HTTPS uses Python's normal certificate verification. For another
+machine use a trusted SSH tunnel to a local numeric loopback port; remote file
+paths and metadata then belong to that daemon, so upload/download local path
+checks assume the CLI and BoFileX share the same filesystem.
+
+## Transfer and channel semantics
+
+- Upload/download **queue a server-side single-file job**. File bytes do not
+  pass through Python. A successful command returns a job ID, not a completed
+  transfer. Inspect `transfer list` for queued/active/done/error/canceled states.
+  Exiting or interrupting the CLI does not cancel submitted work.
+- Upload source paths are resolved to absolute paths and must be regular local
+  files. Size comes from the file stat. The destination is a remote directory;
+  `--name` changes the destination basename. Directory recursion is not included.
+- Download targets are existing local directories, resolved to absolute paths.
+  Use `files list` to obtain the remote `path`, `size` and `mtime` (Unix seconds).
+  `--size` is required, including `--size 0` for an empty file. No metadata lookup
+  happens implicitly. `--mtime` defaults to zero (unknown). `--overwrite` opts
+  into replacing a local destination; otherwise BoFileX chooses a free name.
+  Remote upload conflict handling remains the daemon's behavior.
+- Cancel is the daemon's idempotent operation: it may return `status: ok` even
+  for an unknown ID. Resume acts on the **same existing job** and its `.part`
+  data; the daemon rejects jobs it cannot continue. Queue durability across a
+  daemon restart is not promised by this CLI.
+- A message response `sent: true` means **accepted for asynchronous delivery**.
+  The daemon may subsequently queue/retry delivery or record a refusal.
+- `channels list PEER_ID` can focus the engine on that peer when no UI socket
+  holds focus. An open UI socket may retain focus instead; check the response's
+  `peer`. `channels select` and `channels mode` change the **shared currently
+  focused engine**, not a per-command or per-peer isolated session. Selecting
+  `auto` sends an empty pin; selecting all directions clears directional pins.
+  A pin may fall back to another ready path. `direct`/`relay` modes clear pins.
+- `files list` can update the daemon's remembered remote pane directory.
+  `peers` may refresh discovery. These are existing API side effects.
+
+## Output, errors and API mapping
+
+`--json` prints the API response as one JSON value on stdout. Human output is
+pretty JSON except for explicit message submission/transfer queue acknowledgments.
+Operational errors use stderr (a JSON `{"error": "..."}` object with `--json`),
+with no traceback or HTTP response body dump. API `error` fields fail even when
+HTTP status is 200. HTTP responses are limited to 8 MiB.
+
+Exit codes: `0` success, `1` operational/API error, `2` argparse usage error,
+`130` interrupted. Argparse usage errors remain standard text, including with
+`--json`. A timeout or lost connection does not prove that a mutation failed;
+check daemon state before submitting it again.
+
+| Command | Local route | Method / query |
+| --- | --- | --- |
+| `info` | `/api/info` | GET |
+| `peers` | `/api/peers` | GET |
+| `message send` | `/api/peers/chat/send` | POST; peer, text |
+| `files list` | `/api/remote/listdir` | GET; peer, path |
+| `transfer list` | `/api/transfers` | GET |
+| `transfer upload/download` | `/api/transfer/add` | POST; peer, peername, dir=up/down, src, target, name, size; download: mtime, overwrite |
+| `transfer cancel/resume` | `/api/transfer/cancel`, `/api/transfer/resume` | POST; id |
+| `channels list` | `/api/peers/channels` | GET; peer |
+| `channels select` | `/api/peers/channels/select` | POST; name, dir=empty/up/down |
+| `channels mode` | `/api/peers/channels/mode` | POST; mode=auto/direct/relay |
+
+Mutations use POST with **URL query parameters and an empty body**, matching
+the Go handlers' `r.URL.Query()` implementation. Do not log full request URLs
+if message content or filesystem paths are sensitive. Peer IDs and paths are
+encoded query values and can never change the HTTP destination.
+
+## Test, build and release handoff
+
+From this directory (PowerShell):
+
+```powershell
+$env:PYTHONPATH = "$PWD/src"
+python -m unittest discover -s tests -v
+python -m build
+```
+
+Tests use only ephemeral loopback mock HTTP servers and temporary files. No
+test contacts a running BoFileX, reads real tokens, starts/stops services, or
+publishes anything. Coverage includes route/query contracts, file metadata,
+Unicode escaping, cookie auth, redirects, proxy isolation, URL restrictions,
+JSON/API errors, and validation before any mutation.
+
+`python -m build` creates `dist/bofile-0.1.0-py3-none-any.whl` and
+`dist/bofile-0.1.0.tar.gz`. Setuptools is a build dependency only. The sdist
+includes the tests. Review package metadata, ownership/licensing and release
+version before publication; PyPI name availability does not reserve a name.
+The release owner handles PyPI credentials, final validation and publishing.
+This implementation deliberately does not upload to PyPI or TestPyPI.

bofile-0.1.0/README.md

@@ -0,0 +1,171 @@
+# bofile — Python CLI for BoFileX
+
+Control a **running local BoFileX** using its existing HTTP API. The PyPI
+distribution, Python module and console command are all named `bofile`.
+Python 3.10+; **no runtime dependencies**. This package does not include the
+BoFileX daemon or implement libp2p, start services, or create machine state.
+
+## Install and run
+
+After publication:
+
+```sh
+python -m pip install bofile
+bofile --help
+python -m bofile --version
+```
+
+From this directory during development:
+
+```sh
+python -m pip install -e .
+python -m bofile --help
+```
+
+The default API origin is `http://127.0.0.1:34120`, set by
+`client/bofilex_main.go`. BoFileX can choose another free port if that port is
+busy: use the actual HTTP UI origin explicitly. A native-only Wails window may
+not expose this HTTP API. The old dialer API on port 34115 is a different API
+and is not supported here.
+
+```sh
+bofile --base-url http://127.0.0.1:34120 info
+bofile peers --json
+bofile message send PEER_ID "你好，文件已经准备好了"
+bofile files list PEER_ID . --json
+bofile transfer upload PEER_ID ./report.pdf /shared
+bofile transfer download PEER_ID /shared/report.pdf ./downloads --size 12345 --mtime 1700000000
+bofile transfer list --json
+bofile transfer cancel 42
+bofile transfer resume 42
+bofile channels list PEER_ID
+bofile channels select nat --direction up
+bofile channels select auto
+bofile channels mode direct
+bofile channels mode auto
+```
+
+Replace `PEER_ID` with a full peer ID from `peers`. Global flags (`--base-url`,
+`--token-file`, `--timeout`, `--json`) work before or after subcommands.
+Each command supports `--help`. This CLI defaults to a 30-second HTTP timeout.
+There is no automatic retry, since resubmitting a mutation could duplicate work.
+
+## Authentication and connection safety
+
+`core/modules/admin/guard.go` allows non-browser scripts that omit Origin,
+Referer and Sec-Fetch-Site. The CLI uses that contract by default and **does not
+read any token, configuration, identity or state file automatically**.
+It never fetches the UI page to harvest a session cookie.
+
+When a persisted UI token is needed, explicitly select the existing file:
+
+```sh
+bofile --token-file /path/to/ui-session.token info
+```
+
+The file must contain the 32-character hex UI token. It is sent as the cookie
+`bofile_ui_<API-port>`, not as a Bearer token or query parameter. No token option
+accepts the raw secret on the command line. The file is read only and is never
+created or refreshed. Invalid/missing explicit files fail rather than falling
+back silently. A 401/403 is an error; remote management password login is not
+implemented.
+
+BoFileX resolves its own state using `BOFILE_STATE_DIR`, or on Windows usually
+`%ProgramData%\bofilex`, otherwise the platform user config directory with the
+`bofilex` namespace (and native fallback rules). Choose the file used by your
+instance explicitly; this CLI does not reproduce the daemon's state migration
+or executable-directory fallback logic.
+
+Only **numeric loopback origins** are accepted (`127.0.0.1`, `[::1]`); DNS names,
+including `localhost`, non-loopback IPs, URL credentials, base paths, queries and
+fragments are rejected before reading a token. Environment HTTP proxies are
+disabled. All redirects are refused, even to another loopback port. This keeps
+cookies and local data from being forwarded to a different endpoint or through
+a proxy. HTTPS uses Python's normal certificate verification. For another
+machine use a trusted SSH tunnel to a local numeric loopback port; remote file
+paths and metadata then belong to that daemon, so upload/download local path
+checks assume the CLI and BoFileX share the same filesystem.
+
+## Transfer and channel semantics
+
+- Upload/download **queue a server-side single-file job**. File bytes do not
+  pass through Python. A successful command returns a job ID, not a completed
+  transfer. Inspect `transfer list` for queued/active/done/error/canceled states.
+  Exiting or interrupting the CLI does not cancel submitted work.
+- Upload source paths are resolved to absolute paths and must be regular local
+  files. Size comes from the file stat. The destination is a remote directory;
+  `--name` changes the destination basename. Directory recursion is not included.
+- Download targets are existing local directories, resolved to absolute paths.
+  Use `files list` to obtain the remote `path`, `size` and `mtime` (Unix seconds).
+  `--size` is required, including `--size 0` for an empty file. No metadata lookup
+  happens implicitly. `--mtime` defaults to zero (unknown). `--overwrite` opts
+  into replacing a local destination; otherwise BoFileX chooses a free name.
+  Remote upload conflict handling remains the daemon's behavior.
+- Cancel is the daemon's idempotent operation: it may return `status: ok` even
+  for an unknown ID. Resume acts on the **same existing job** and its `.part`
+  data; the daemon rejects jobs it cannot continue. Queue durability across a
+  daemon restart is not promised by this CLI.
+- A message response `sent: true` means **accepted for asynchronous delivery**.
+  The daemon may subsequently queue/retry delivery or record a refusal.
+- `channels list PEER_ID` can focus the engine on that peer when no UI socket
+  holds focus. An open UI socket may retain focus instead; check the response's
+  `peer`. `channels select` and `channels mode` change the **shared currently
+  focused engine**, not a per-command or per-peer isolated session. Selecting
+  `auto` sends an empty pin; selecting all directions clears directional pins.
+  A pin may fall back to another ready path. `direct`/`relay` modes clear pins.
+- `files list` can update the daemon's remembered remote pane directory.
+  `peers` may refresh discovery. These are existing API side effects.
+
+## Output, errors and API mapping
+
+`--json` prints the API response as one JSON value on stdout. Human output is
+pretty JSON except for explicit message submission/transfer queue acknowledgments.
+Operational errors use stderr (a JSON `{"error": "..."}` object with `--json`),
+with no traceback or HTTP response body dump. API `error` fields fail even when
+HTTP status is 200. HTTP responses are limited to 8 MiB.
+
+Exit codes: `0` success, `1` operational/API error, `2` argparse usage error,
+`130` interrupted. Argparse usage errors remain standard text, including with
+`--json`. A timeout or lost connection does not prove that a mutation failed;
+check daemon state before submitting it again.
+
+| Command | Local route | Method / query |
+| --- | --- | --- |
+| `info` | `/api/info` | GET |
+| `peers` | `/api/peers` | GET |
+| `message send` | `/api/peers/chat/send` | POST; peer, text |
+| `files list` | `/api/remote/listdir` | GET; peer, path |
+| `transfer list` | `/api/transfers` | GET |
+| `transfer upload/download` | `/api/transfer/add` | POST; peer, peername, dir=up/down, src, target, name, size; download: mtime, overwrite |
+| `transfer cancel/resume` | `/api/transfer/cancel`, `/api/transfer/resume` | POST; id |
+| `channels list` | `/api/peers/channels` | GET; peer |
+| `channels select` | `/api/peers/channels/select` | POST; name, dir=empty/up/down |
+| `channels mode` | `/api/peers/channels/mode` | POST; mode=auto/direct/relay |
+
+Mutations use POST with **URL query parameters and an empty body**, matching
+the Go handlers' `r.URL.Query()` implementation. Do not log full request URLs
+if message content or filesystem paths are sensitive. Peer IDs and paths are
+encoded query values and can never change the HTTP destination.
+
+## Test, build and release handoff
+
+From this directory (PowerShell):
+
+```powershell
+$env:PYTHONPATH = "$PWD/src"
+python -m unittest discover -s tests -v
+python -m build
+```
+
+Tests use only ephemeral loopback mock HTTP servers and temporary files. No
+test contacts a running BoFileX, reads real tokens, starts/stops services, or
+publishes anything. Coverage includes route/query contracts, file metadata,
+Unicode escaping, cookie auth, redirects, proxy isolation, URL restrictions,
+JSON/API errors, and validation before any mutation.
+
+`python -m build` creates `dist/bofile-0.1.0-py3-none-any.whl` and
+`dist/bofile-0.1.0.tar.gz`. Setuptools is a build dependency only. The sdist
+includes the tests. Review package metadata, ownership/licensing and release
+version before publication; PyPI name availability does not reserve a name.
+The release owner handles PyPI credentials, final validation and publishing.
+This implementation deliberately does not upload to PyPI or TestPyPI.

bofile-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bofile"
+version = "0.1.0"
+description = "Standard-library CLI for the local BoFileX HTTP API"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["bofile", "bofilex", "cli", "file-transfer"]
+license = "LicenseRef-Proprietary"
+classifiers = [
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: File Sharing",
+]
+
+[project.urls]
+Homepage = "https://bofile.com/"
+Documentation = "https://bofile.com/install.html"
+
+[project.scripts]
+bofile = "bofile.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

bofile-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bofile-0.1.0/src/bofile/__init__.py

@@ -0,0 +1,3 @@
+"""A local HTTP client for BoFileX, with no runtime dependencies."""
+
+__version__ = "0.1.0"

bofile-0.1.0/src/bofile/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

bofile-0.1.0/src/bofile/cli.py

@@ -0,0 +1,196 @@
+"""Command parsing and the BoFileX peer API mapping."""
+
+import argparse
+import json
+import math
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .client import BofileError, Client, DEFAULT_BASE_URL
+
+
+def nonempty(value):
+    if not value.strip():
+        raise argparse.ArgumentTypeError("must not be empty")
+    return value
+
+
+def nonnegative(value):
+    try:
+        number = int(value)
+        if not 0 <= number <= 2**63 - 1:
+            raise ValueError
+        return number
+    except ValueError:
+        raise argparse.ArgumentTypeError("must be an integer from 0 to 9223372036854775807") from None
+
+
+def positive(value):
+    number = nonnegative(value)
+    if not number:
+        raise argparse.ArgumentTypeError("must be greater than zero")
+    return number
+
+
+def timeout_value(value):
+    try:
+        number = float(value)
+        if not math.isfinite(number) or number <= 0:
+            raise ValueError
+        return number
+    except ValueError:
+        raise argparse.ArgumentTypeError("must be a finite positive number") from None
+
+
+def global_options(parser, *, root=False):
+    # Suppressed child defaults allow options both before and after subcommands.
+    def default(value):
+        return value if root else argparse.SUPPRESS
+    parser.add_argument("--base-url", default=default(DEFAULT_BASE_URL),
+                        help="numeric loopback HTTP origin (default: http://127.0.0.1:34120)")
+    parser.add_argument("--token-file", default=default(None),
+                        help="explicit ui-session.token file; never auto-discovered")
+    parser.add_argument("--timeout", type=timeout_value, default=default(30),
+                        help="HTTP timeout in seconds (default: 30)")
+    parser.add_argument("--json", action="store_true", default=default(False),
+                        help="machine-readable JSON output (and operational errors)")
+
+
+def parser():
+    root = argparse.ArgumentParser(
+        prog="bofile", description="Control a running local BoFileX through its HTTP API.",
+        epilog="No daemon is started. Jobs run in BoFileX after this command exits.")
+    global_options(root, root=True)
+    root.add_argument("--version", action="version", version="bofile " + __version__)
+    commands = root.add_subparsers(dest="command", required=True)
+
+    def add(subs, name, help_text):
+        child = subs.add_parser(name, help=help_text, description=help_text)
+        global_options(child)
+        return child
+
+    add(commands, "info", "Show local instance information.")
+    add(commands, "peers", "List known circle peers (may refresh discovery).")
+    message = add(commands, "message", "Send text to a peer.")
+    send = add(message.add_subparsers(dest="action", required=True), "send",
+               "Submit a message; accepted does not mean delivered.")
+    send.add_argument("peer", type=nonempty, help="full peer ID")
+    send.add_argument("text", type=nonempty, help="message text; quote spaces")
+
+    transfer = add(commands, "transfer", "Manage server-side single-file transfer jobs.")
+    transfers = transfer.add_subparsers(dest="action", required=True)
+    add(transfers, "list", "List the entire local transfer queue.")
+    for action in ("upload", "download"):
+        p = add(transfers, action, "Queue a single-file " + action + ". Paths belong to the local BoFileX host.")
+        p.add_argument("peer", type=nonempty, help="full destination/source peer ID")
+        p.add_argument("source", type=nonempty, help="local file" if action == "upload" else "remote file path")
+        p.add_argument("target", type=nonempty, help="remote directory" if action == "upload" else "existing local directory")
+        p.add_argument("--name", type=nonempty, help="destination basename (default: source basename)")
+        p.add_argument("--peer-name", default="", help="optional display label recorded on the job")
+        if action == "download":
+            p.add_argument("--size", type=nonnegative, required=True, help="remote file size in bytes; use files list")
+            p.add_argument("--mtime", type=nonnegative, default=0, help="remote Unix mtime in seconds")
+            p.add_argument("--overwrite", action="store_true", help="replace an existing local destination; default chooses a free name")
+    for action in ("cancel", "resume"):
+        p = add(transfers, action, action.capitalize() + " an existing transfer ID.")
+        p.add_argument("id", type=positive)
+
+    channels = add(commands, "channels", "Inspect or change the shared channel engine.")
+    channel_subs = channels.add_subparsers(dest="action", required=True)
+    p = add(channel_subs, "list", "List channels for a peer; may focus the engine when no UI socket is open.")
+    p.add_argument("peer", type=nonempty)
+    p = add(channel_subs, "select", "Pin a channel on the currently focused engine (shared with the UI).")
+    p.add_argument("name", type=nonempty, help="channel name, or auto to clear the pin")
+    p.add_argument("--direction", choices=("all", "up", "down"), default="all")
+    p = add(channel_subs, "mode", "Set shared engine routing mode; direct/relay clear channel pins.")
+    p.add_argument("mode", choices=("auto", "direct", "relay"))
+
+    files = add(commands, "files", "Inspect remote file metadata before downloading.")
+    p = add(files.add_subparsers(dest="action", required=True), "list",
+            "List a remote directory; BoFileX remembers the pane directory.")
+    p.add_argument("peer", type=nonempty)
+    p.add_argument("path", nargs="?", default=".", help="remote directory (default: shared root .)")
+    return root
+
+
+def basename(value):
+    return value.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+
+
+def safe_name(value):
+    if value in ("", ".", "..") or any(c in value for c in ("/", "\\", ":", "\x00")):
+        raise BofileError("destination name must be a basename without path separators or drive prefix")
+    return value
+
+
+def execute(args, client):
+    if args.command in ("info", "peers"):
+        return client.request("/api/" + args.command)
+    if args.command == "message":
+        return client.request("/api/peers/chat/send", {"peer": args.peer, "text": args.text}, mutate=True)
+    if args.command == "files":
+        return client.request("/api/remote/listdir", {"peer": args.peer, "path": args.path})
+    if args.command == "channels":
+        if args.action == "list":
+            return client.request("/api/peers/channels", {"peer": args.peer})
+        if args.action == "mode":
+            return client.request("/api/peers/channels/mode", {"mode": args.mode}, mutate=True)
+        return client.request("/api/peers/channels/select", {
+            "name": "" if args.name == "auto" else args.name,
+            "dir": "" if args.direction == "all" else args.direction,
+        }, mutate=True)
+    if args.action == "list":
+        return client.request("/api/transfers")
+    if args.action in ("cancel", "resume"):
+        return client.request("/api/transfer/" + args.action, {"id": args.id}, mutate=True)
+    name = safe_name(args.name or basename(args.source))
+    if args.action == "upload":
+        source = Path(args.source).expanduser().resolve()
+        if not source.is_file():
+            raise BofileError("upload source must be an existing regular file")
+        size = source.stat().st_size
+        if size > 2**63 - 1:
+            raise BofileError("upload source exceeds the API size limit")
+        params = {"dir": "up", "src": str(source), "target": args.target, "size": size}
+    else:
+        target = Path(args.target).expanduser().resolve()
+        if not target.is_dir():
+            raise BofileError("download target must be an existing local directory")
+        params = {"dir": "down", "src": args.source, "target": str(target),
+                  "size": args.size, "mtime": args.mtime, "overwrite": "1" if args.overwrite else "0"}
+    params.update(peer=args.peer, peername=args.peer_name, name=name)
+    return client.request("/api/transfer/add", params, mutate=True)
+
+
+def human_output(result, args):
+    if isinstance(result, dict):
+        if args.command == "message" and result.get("sent"):
+            return "Message accepted (delivery is asynchronous). ID: " + str(result.get("id", "unknown"))
+        if args.command == "transfer" and args.action in ("upload", "download") and "id" in result:
+            return f"Transfer queued. ID: {result['id']} (use bofile transfer list to check progress)"
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        client = Client(args.base_url, timeout=args.timeout, token_file=args.token_file)
+        result = execute(args, client)
+        print(json.dumps(result, ensure_ascii=False) if args.json else human_output(result, args))
+        return 0
+    except (BofileError, OSError) as exc:
+        detail = str(exc) if isinstance(exc, BofileError) else "cannot access the specified local file or directory"
+        if args.json:
+            print(json.dumps({"error": detail}, ensure_ascii=False), file=sys.stderr)
+        else:
+            print("bofile: " + detail, file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("bofile: interrupted; submitted jobs may still be running", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bofile-0.1.0/src/bofile/client.py

@@ -0,0 +1,133 @@
+"""Bounded, loopback-only transport. Never discovers or writes machine state."""
+
+import ipaddress
+import json
+import math
+import re
+import socket
+from http.client import HTTPException
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlsplit
+from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener
+
+from . import __version__
+
+DEFAULT_BASE_URL = "http://127.0.0.1:34120"
+MAX_RESPONSE = 8 * 1024 * 1024
+
+
+class BofileError(Exception):
+    """An actionable error safe to present without a traceback."""
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def validate_base_url(value):
+    """Accept only literal loopback origins, avoiding DNS rebinding entirely."""
+    try:
+        if any(ord(c) <= 32 or ord(c) == 127 for c in value):
+            raise ValueError
+        parsed = urlsplit(value)
+        address = ipaddress.ip_address(parsed.hostname or "")
+        if (
+            parsed.scheme not in ("http", "https")
+            or not address.is_loopback
+            or getattr(address, "ipv4_mapped", None) is not None
+            or "%" in (parsed.hostname or "")
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.path not in ("", "/")
+            or parsed.query
+            or parsed.fragment
+            or "?" in value
+            or "#" in value
+        ):
+            raise ValueError
+        port = parsed.port
+        if port is not None and not 1 <= port <= 65535:
+            raise ValueError
+        if parsed.netloc.endswith(":"):
+            raise ValueError
+    except ValueError:
+        raise BofileError(
+            "--base-url must be an http(s) numeric loopback origin, e.g. "
+            "http://127.0.0.1:34120 or http://[::1]:34120 (no path or credentials)"
+        ) from None
+    return value.rstrip("/"), port or (443 if parsed.scheme == "https" else 80)
+
+
+class Client:
+    def __init__(self, base_url=DEFAULT_BASE_URL, *, timeout=30, token_file=None):
+        # Validate the destination BEFORE reading any local credential.
+        self.base_url, self.port = validate_base_url(base_url)
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise BofileError("--timeout must be a finite positive number")
+        self.timeout = timeout
+        self.token = None
+        if token_file:
+            try:
+                with Path(token_file).open("r", encoding="utf-8") as stream:
+                    token = stream.read(4097).strip()
+            except (OSError, UnicodeError):
+                raise BofileError("cannot read --token-file as UTF-8 text") from None
+            # Tokens minted by NewUISessionToken are 16 random bytes in hex.
+            if not re.fullmatch(r"[0-9a-fA-F]{32}", token):
+                raise BofileError("--token-file must contain a 32-character hex UI session token")
+            self.token = token
+        # Environment proxies must never receive the session cookie or local data.
+        self.opener = build_opener(ProxyHandler({}), NoRedirect())
+
+    def _safe_detail(self, value):
+        text = str(value)
+        if self.token:
+            text = text.replace(self.token, "[redacted]")
+        return "".join(c if c.isprintable() else " " for c in text)[:500]
+
+    def request(self, path, params=None, *, mutate=False):
+        # Fixed API routes only; a peer/path can never replace the destination.
+        if not re.fullmatch(r"/api/[a-z/]+", path):
+            raise BofileError("invalid API route")
+        url = self.base_url + path
+        if params:
+            url += "?" + urlencode(params)
+        headers = {"Accept": "application/json", "User-Agent": "bofile/" + __version__}
+        if self.token:
+            headers["Cookie"] = f"bofile_ui_{self.port}={self.token}"
+        # The Go handlers read URL.Query(), even for POST. Do not use a JSON body.
+        req = Request(url, data=b"" if mutate else None, headers=headers,
+                      method="POST" if mutate else "GET")
+        try:
+            with self.opener.open(req, timeout=self.timeout) as response:
+                payload = response.read(MAX_RESPONSE + 1)
+        except HTTPError as exc:
+            code = exc.code
+            exc.close()
+            if 300 <= code < 400:
+                raise BofileError("HTTP redirect refused; use the local API's exact origin") from None
+            if code in (401, 403):
+                raise BofileError(
+                    f"HTTP {code}: access refused; check the local port and --token-file. "
+                    "Remote management/password login is not supported."
+                ) from None
+            raise BofileError(f"HTTP {code} from local API") from None
+        except (TimeoutError, socket.timeout):
+            raise BofileError("local API timed out; a submitted operation may still be running; inspect state before retrying") from None
+        except HTTPException:
+            raise BofileError("local API connection ended unexpectedly; inspect state before retrying a submitted operation") from None
+        except (URLError, OSError, ValueError):
+            raise BofileError("cannot reach local BoFileX API; start BoFileX with its HTTP UI and check --base-url") from None
+        if len(payload) > MAX_RESPONSE:
+            raise BofileError("local API response exceeds 8 MiB")
+        try:
+            result = json.loads(payload)
+        except (ValueError, UnicodeError, RecursionError):
+            raise BofileError("local API returned invalid JSON; check the port and HTTP UI availability") from None
+        if not isinstance(result, (dict, list)):
+            raise BofileError("local API returned an unexpected JSON shape")
+        if isinstance(result, dict) and result.get("error"):
+            raise BofileError("API: " + self._safe_detail(result["error"]))
+        return result

bofile-0.1.0/src/bofile.egg-info/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: bofile
+Version: 0.1.0
+Summary: Standard-library CLI for the local BoFileX HTTP API
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://bofile.com/
+Project-URL: Documentation, https://bofile.com/install.html
+Keywords: bofile,bofilex,cli,file-transfer
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: File Sharing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bofile — Python CLI for BoFileX
+
+Control a **running local BoFileX** using its existing HTTP API. The PyPI
+distribution, Python module and console command are all named `bofile`.
+Python 3.10+; **no runtime dependencies**. This package does not include the
+BoFileX daemon or implement libp2p, start services, or create machine state.
+
+## Install and run
+
+After publication:
+
+```sh
+python -m pip install bofile
+bofile --help
+python -m bofile --version
+```
+
+From this directory during development:
+
+```sh
+python -m pip install -e .
+python -m bofile --help
+```
+
+The default API origin is `http://127.0.0.1:34120`, set by
+`client/bofilex_main.go`. BoFileX can choose another free port if that port is
+busy: use the actual HTTP UI origin explicitly. A native-only Wails window may
+not expose this HTTP API. The old dialer API on port 34115 is a different API
+and is not supported here.
+
+```sh
+bofile --base-url http://127.0.0.1:34120 info
+bofile peers --json
+bofile message send PEER_ID "你好，文件已经准备好了"
+bofile files list PEER_ID . --json
+bofile transfer upload PEER_ID ./report.pdf /shared
+bofile transfer download PEER_ID /shared/report.pdf ./downloads --size 12345 --mtime 1700000000
+bofile transfer list --json
+bofile transfer cancel 42
+bofile transfer resume 42
+bofile channels list PEER_ID
+bofile channels select nat --direction up
+bofile channels select auto
+bofile channels mode direct
+bofile channels mode auto
+```
+
+Replace `PEER_ID` with a full peer ID from `peers`. Global flags (`--base-url`,
+`--token-file`, `--timeout`, `--json`) work before or after subcommands.
+Each command supports `--help`. This CLI defaults to a 30-second HTTP timeout.
+There is no automatic retry, since resubmitting a mutation could duplicate work.
+
+## Authentication and connection safety
+
+`core/modules/admin/guard.go` allows non-browser scripts that omit Origin,
+Referer and Sec-Fetch-Site. The CLI uses that contract by default and **does not
+read any token, configuration, identity or state file automatically**.
+It never fetches the UI page to harvest a session cookie.
+
+When a persisted UI token is needed, explicitly select the existing file:
+
+```sh
+bofile --token-file /path/to/ui-session.token info
+```
+
+The file must contain the 32-character hex UI token. It is sent as the cookie
+`bofile_ui_<API-port>`, not as a Bearer token or query parameter. No token option
+accepts the raw secret on the command line. The file is read only and is never
+created or refreshed. Invalid/missing explicit files fail rather than falling
+back silently. A 401/403 is an error; remote management password login is not
+implemented.
+
+BoFileX resolves its own state using `BOFILE_STATE_DIR`, or on Windows usually
+`%ProgramData%\bofilex`, otherwise the platform user config directory with the
+`bofilex` namespace (and native fallback rules). Choose the file used by your
+instance explicitly; this CLI does not reproduce the daemon's state migration
+or executable-directory fallback logic.
+
+Only **numeric loopback origins** are accepted (`127.0.0.1`, `[::1]`); DNS names,
+including `localhost`, non-loopback IPs, URL credentials, base paths, queries and
+fragments are rejected before reading a token. Environment HTTP proxies are
+disabled. All redirects are refused, even to another loopback port. This keeps
+cookies and local data from being forwarded to a different endpoint or through
+a proxy. HTTPS uses Python's normal certificate verification. For another
+machine use a trusted SSH tunnel to a local numeric loopback port; remote file
+paths and metadata then belong to that daemon, so upload/download local path
+checks assume the CLI and BoFileX share the same filesystem.
+
+## Transfer and channel semantics
+
+- Upload/download **queue a server-side single-file job**. File bytes do not
+  pass through Python. A successful command returns a job ID, not a completed
+  transfer. Inspect `transfer list` for queued/active/done/error/canceled states.
+  Exiting or interrupting the CLI does not cancel submitted work.
+- Upload source paths are resolved to absolute paths and must be regular local
+  files. Size comes from the file stat. The destination is a remote directory;
+  `--name` changes the destination basename. Directory recursion is not included.
+- Download targets are existing local directories, resolved to absolute paths.
+  Use `files list` to obtain the remote `path`, `size` and `mtime` (Unix seconds).
+  `--size` is required, including `--size 0` for an empty file. No metadata lookup
+  happens implicitly. `--mtime` defaults to zero (unknown). `--overwrite` opts
+  into replacing a local destination; otherwise BoFileX chooses a free name.
+  Remote upload conflict handling remains the daemon's behavior.
+- Cancel is the daemon's idempotent operation: it may return `status: ok` even
+  for an unknown ID. Resume acts on the **same existing job** and its `.part`
+  data; the daemon rejects jobs it cannot continue. Queue durability across a
+  daemon restart is not promised by this CLI.
+- A message response `sent: true` means **accepted for asynchronous delivery**.
+  The daemon may subsequently queue/retry delivery or record a refusal.
+- `channels list PEER_ID` can focus the engine on that peer when no UI socket
+  holds focus. An open UI socket may retain focus instead; check the response's
+  `peer`. `channels select` and `channels mode` change the **shared currently
+  focused engine**, not a per-command or per-peer isolated session. Selecting
+  `auto` sends an empty pin; selecting all directions clears directional pins.
+  A pin may fall back to another ready path. `direct`/`relay` modes clear pins.
+- `files list` can update the daemon's remembered remote pane directory.
+  `peers` may refresh discovery. These are existing API side effects.
+
+## Output, errors and API mapping
+
+`--json` prints the API response as one JSON value on stdout. Human output is
+pretty JSON except for explicit message submission/transfer queue acknowledgments.
+Operational errors use stderr (a JSON `{"error": "..."}` object with `--json`),
+with no traceback or HTTP response body dump. API `error` fields fail even when
+HTTP status is 200. HTTP responses are limited to 8 MiB.
+
+Exit codes: `0` success, `1` operational/API error, `2` argparse usage error,
+`130` interrupted. Argparse usage errors remain standard text, including with
+`--json`. A timeout or lost connection does not prove that a mutation failed;
+check daemon state before submitting it again.
+
+| Command | Local route | Method / query |
+| --- | --- | --- |
+| `info` | `/api/info` | GET |
+| `peers` | `/api/peers` | GET |
+| `message send` | `/api/peers/chat/send` | POST; peer, text |
+| `files list` | `/api/remote/listdir` | GET; peer, path |
+| `transfer list` | `/api/transfers` | GET |
+| `transfer upload/download` | `/api/transfer/add` | POST; peer, peername, dir=up/down, src, target, name, size; download: mtime, overwrite |
+| `transfer cancel/resume` | `/api/transfer/cancel`, `/api/transfer/resume` | POST; id |
+| `channels list` | `/api/peers/channels` | GET; peer |
+| `channels select` | `/api/peers/channels/select` | POST; name, dir=empty/up/down |
+| `channels mode` | `/api/peers/channels/mode` | POST; mode=auto/direct/relay |
+
+Mutations use POST with **URL query parameters and an empty body**, matching
+the Go handlers' `r.URL.Query()` implementation. Do not log full request URLs
+if message content or filesystem paths are sensitive. Peer IDs and paths are
+encoded query values and can never change the HTTP destination.
+
+## Test, build and release handoff
+
+From this directory (PowerShell):
+
+```powershell
+$env:PYTHONPATH = "$PWD/src"
+python -m unittest discover -s tests -v
+python -m build
+```
+
+Tests use only ephemeral loopback mock HTTP servers and temporary files. No
+test contacts a running BoFileX, reads real tokens, starts/stops services, or
+publishes anything. Coverage includes route/query contracts, file metadata,
+Unicode escaping, cookie auth, redirects, proxy isolation, URL restrictions,
+JSON/API errors, and validation before any mutation.
+
+`python -m build` creates `dist/bofile-0.1.0-py3-none-any.whl` and
+`dist/bofile-0.1.0.tar.gz`. Setuptools is a build dependency only. The sdist
+includes the tests. Review package metadata, ownership/licensing and release
+version before publication; PyPI name availability does not reserve a name.
+The release owner handles PyPI credentials, final validation and publishing.
+This implementation deliberately does not upload to PyPI or TestPyPI.

bofile-0.1.0/src/bofile.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/bofile/__init__.py
+src/bofile/__main__.py
+src/bofile/cli.py
+src/bofile/client.py
+src/bofile.egg-info/PKG-INFO
+src/bofile.egg-info/SOURCES.txt
+src/bofile.egg-info/dependency_links.txt
+src/bofile.egg-info/entry_points.txt
+src/bofile.egg-info/top_level.txt
+tests/test_cli.py

bofile-0.1.0/src/bofile.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bofile-0.1.0/src/bofile.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bofile = bofile.cli:main

bofile-0.1.0/src/bofile.egg-info/top_level.txt

@@ -0,0 +1 @@
+bofile

bofile-0.1.0/tests/test_cli.py

@@ -0,0 +1,326 @@
+"""All HTTP traffic goes to this suite's ephemeral mock server, never BoFileX."""
+
+import contextlib
+import io
+import json
+import os
+import tempfile
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from unittest.mock import patch
+from urllib.parse import parse_qs, urlsplit
+
+from bofile.cli import main
+from bofile.client import BofileError, Client, validate_base_url
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+    def do_GET(self):
+        self.dispatch()
+
+    def do_POST(self):
+        self.dispatch()
+
+    def dispatch(self):
+        parsed = urlsplit(self.path)
+        self.server.calls.append({
+            "method": self.command, "path": parsed.path,
+            "query": parse_qs(parsed.query, keep_blank_values=True),
+            "headers": dict(self.headers),
+            "body": self.rfile.read(int(self.headers.get("Content-Length", 0))),
+        })
+        self.send_response(self.server.status)
+        if self.server.location:
+            self.send_header("Location", self.server.location)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(self.server.payload)
+
+
+class CLITests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        cls.base = f"http://127.0.0.1:{cls.server.server_port}"
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+        cls.thread.join()
+
+    def setUp(self):
+        self.server.calls = []
+        self.server.status = 200
+        self.server.location = None
+        self.server.payload = b'{"status":"ok"}'
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.folder = Path(self.tmp.name)
+
+    def run_cli(self, *args, root_options=()):
+        out, err = io.StringIO(), io.StringIO()
+        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            code = main(["--base-url", self.base, *root_options, *args])
+        return code, out.getvalue(), err.getvalue()
+
+    def query(self):
+        return self.server.calls[-1]["query"]
+
+    def test_read_routes_and_json(self):
+        for command, route in (("info", "/api/info"), ("peers", "/api/peers")):
+            with self.subTest(command=command):
+                self.server.payload = json.dumps({command: []}).encode()
+                code, out, err = self.run_cli(command, "--json")
+                self.assertEqual((code, err), (0, ""))
+                self.assertEqual(json.loads(out), {command: []})
+                self.assertEqual(self.server.calls[-1]["path"], route)
+                self.assertEqual(self.server.calls[-1]["method"], "GET")
+
+    def test_options_at_all_levels(self):
+        code, out, err = self.run_cli("transfer", "--json", "list")
+        self.assertEqual((code, err), (0, ""))
+        self.assertEqual(json.loads(out), {"status": "ok"})
+        code, out, err = self.run_cli("transfer", "list", root_options=("--json",))
+        self.assertEqual(code, 0)
+        self.assertEqual(json.loads(out), {"status": "ok"})
+
+    def test_message_unicode_and_query_injection_are_encoded(self):
+        self.server.payload = b'{"sent":true,"id":"message-1"}'
+        text = "你好 &peer=attacker #/? plus+\nline"
+        code, out, err = self.run_cli("message", "send", "peer-1", text)
+        self.assertEqual((code, err), (0, ""))
+        self.assertIn("asynchronous", out)
+        self.assertEqual(self.query(), {"peer": ["peer-1"], "text": [text]})
+        call = self.server.calls[-1]
+        self.assertEqual((call["method"], call["path"], call["body"]),
+                         ("POST", "/api/peers/chat/send", b""))
+
+    def test_upload_uses_local_file_metadata_and_server_job(self):
+        source = self.folder / "报告 &1.txt"
+        source.write_bytes(b"hello")
+        self.server.payload = b'{"id":42}'
+        code, out, err = self.run_cli("transfer", "upload", "peer-1", str(source),
+                                      "/remote &folder", "--peer-name", "Alice")
+        self.assertEqual((code, err), (0, ""))
+        self.assertIn("queued", out)
+        self.assertEqual(self.server.calls[-1]["path"], "/api/transfer/add")
+        self.assertEqual(self.query(), {"dir": ["up"], "src": [str(source.resolve())],
+            "target": ["/remote &folder"], "size": ["5"], "peer": ["peer-1"],
+            "peername": ["Alice"], "name": [source.name]})
+        self.assertEqual(source.read_bytes(), b"hello")
+
+    def test_download_exact_contract_and_no_local_write(self):
+        code, out, err = self.run_cli("transfer", "download", "peer-1", "D:\\共享\\报告.pdf",
+            str(self.folder), "--size", "0", "--mtime", "1700000000", "--overwrite", "--json")
+        self.assertEqual((code, err), (0, ""))
+        self.assertEqual(self.query(), {"dir": ["down"], "src": ["D:\\共享\\报告.pdf"],
+            "target": [str(self.folder.resolve())], "size": ["0"], "mtime": ["1700000000"],
+            "overwrite": ["1"], "peer": ["peer-1"], "peername": [""], "name": ["报告.pdf"]})
+        self.assertEqual(list(self.folder.iterdir()), [])
+
+    def test_download_rename_without_overwrite(self):
+        code, _, _ = self.run_cli("transfer", "download", "p", "/one.txt", str(self.folder),
+                                  "--size", "10", "--name", "two.txt")
+        self.assertEqual(code, 0)
+        self.assertEqual(self.query()["overwrite"], ["0"])
+        self.assertEqual(self.query()["name"], ["two.txt"])
+
+    def test_invalid_local_paths_do_not_send(self):
+        cases = [
+            ("transfer", "upload", "p", str(self.folder), "."),
+            ("transfer", "upload", "p", str(self.folder / "missing"), "."),
+            ("transfer", "download", "p", "file", str(self.folder / "missing"), "--size", "1"),
+            ("transfer", "download", "p", "file", str(self.folder), "--size", "1", "--name", "../escape"),
+            ("transfer", "download", "p", "file", str(self.folder), "--size", "1", "--name", "C:escape"),
+        ]
+        for args in cases:
+            with self.subTest(args=args):
+                code, out, err = self.run_cli(*args)
+                self.assertEqual(code, 1)
+                self.assertEqual(out, "")
+                self.assertIn("bofile:", err)
+        self.assertEqual(self.server.calls, [])
+
+    def test_transfer_list_cancel_resume(self):
+        for action, route in (("list", "/api/transfers"), ("cancel", "/api/transfer/cancel"),
+                              ("resume", "/api/transfer/resume")):
+            with self.subTest(action=action):
+                args = ("transfer", action) + (() if action == "list" else ("42",))
+                code, _, err = self.run_cli(*args)
+                self.assertEqual((code, err), (0, ""))
+                self.assertEqual(self.server.calls[-1]["path"], route)
+                self.assertEqual(self.query(), {} if action == "list" else {"id": ["42"]})
+                self.assertEqual(self.server.calls[-1]["method"], "GET" if action == "list" else "POST")
+
+    def test_channels_contract(self):
+        cases = [
+            (("channels", "list", "peer-1"), "/api/peers/channels", {"peer": ["peer-1"]}),
+            (("channels", "select", "auto"), "/api/peers/channels/select", {"name": [""], "dir": [""]}),
+            (("channels", "select", "nat", "--direction", "up"), "/api/peers/channels/select", {"name": ["nat"], "dir": ["up"]}),
+            (("channels", "mode", "relay"), "/api/peers/channels/mode", {"mode": ["relay"]}),
+        ]
+        for args, route, query in cases:
+            with self.subTest(args=args):
+                code, _, err = self.run_cli(*args)
+                self.assertEqual((code, err), (0, ""))
+                self.assertEqual(self.server.calls[-1]["path"], route)
+                self.assertEqual(self.query(), query)
+
+    def test_remote_metadata(self):
+        code, _, _ = self.run_cli("files", "list", "p", "/shared &stuff")
+        self.assertEqual(code, 0)
+        self.assertEqual(self.server.calls[-1]["path"], "/api/remote/listdir")
+        self.assertEqual(self.query(), {"peer": ["p"], "path": ["/shared &stuff"]})
+
+    def test_token_cookie_and_no_browser_headers(self):
+        token = "a" * 32
+        token_file = self.folder / "ui-session.token"
+        token_file.write_text(token + "\n")
+        code, _, err = self.run_cli("info", "--token-file", str(token_file))
+        self.assertEqual((code, err), (0, ""))
+        headers = self.server.calls[-1]["headers"]
+        self.assertEqual(headers["Cookie"], f"bofile_ui_{self.server.server_port}={token}")
+        for name in ("Origin", "Referer", "Sec-Fetch-Site", "Authorization"):
+            self.assertNotIn(name, headers)
+        self.assertEqual(token_file.read_text(), token + "\n")
+
+    def test_default_does_not_read_or_create_state(self):
+        with patch("pathlib.Path.open", side_effect=AssertionError("unexpected state read")):
+            with patch.dict(os.environ, {"BOFILE_STATE_DIR": str(self.folder)}):
+                code, _, _ = self.run_cli("info")
+        self.assertEqual(code, 0)
+        self.assertNotIn("Cookie", self.server.calls[-1]["headers"])
+        self.assertEqual(list(self.folder.iterdir()), [])
+
+    def test_invalid_destination_precedes_credential_read(self):
+        with patch("pathlib.Path.open", side_effect=AssertionError("must not read token")):
+            with self.assertRaises(BofileError):
+                Client("https://evil.example", token_file="ui-session.token")
+
+    def test_bad_token_files(self):
+        token_file = self.folder / "token"
+        for token in ("", "a" * 4097, "a" * 32 + ";evil=yes", "a" * 32 + "\r\nX: evil"):
+            token_file.write_text(token)
+            with self.subTest(token=token[:40]):
+                self.assertEqual(self.run_cli("info", "--token-file", str(token_file))[0], 1)
+        self.assertEqual(self.run_cli("info", "--token-file", str(self.folder / "missing"))[0], 1)
+        self.assertEqual(self.server.calls, [])
+
+    def test_api_error_at_http_200_and_json_error_redaction(self):
+        token = "b" * 32
+        token_file = self.folder / "token"
+        token_file.write_text(token)
+        self.server.payload = json.dumps({"error": "refused\x1b " + token}).encode()
+        code, out, err = self.run_cli("transfer", "resume", "4", "--json", "--token-file", str(token_file))
+        self.assertEqual((code, out), (1, ""))
+        self.assertNotIn(token, err)
+        self.assertIn("[redacted]", json.loads(err)["error"])
+        self.assertNotIn("\x1b", json.loads(err)["error"])
+
+    def test_http_errors_hide_bodies_and_credentials(self):
+        for status in (401, 403, 404, 500):
+            self.server.status = status
+            self.server.payload = b"secret in error body"
+            code, out, err = self.run_cli("info", "--json")
+            self.assertEqual((code, out), (1, ""))
+            self.assertIn(str(status), json.loads(err)["error"])
+            self.assertNotIn("secret", err)
+
+    def test_redirect_never_contacts_destination(self):
+        sink = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        sink.calls = []
+        thread = threading.Thread(target=sink.serve_forever, daemon=True)
+        thread.start()
+        try:
+            token_file = self.folder / "token"
+            token_file.write_text("c" * 32)
+            for status in (301, 302, 303, 307, 308):
+                self.server.status = status
+                self.server.location = f"http://127.0.0.1:{sink.server_port}/leak"
+                code, _, err = self.run_cli("info", "--token-file", str(token_file))
+                self.assertEqual(code, 1)
+                self.assertIn("redirect refused", err)
+            self.assertEqual(sink.calls, [])
+        finally:
+            sink.shutdown()
+            sink.server_close()
+            thread.join()
+
+    def test_environment_proxy_is_ignored(self):
+        with patch.dict(os.environ, {"http_proxy": "http://127.0.0.1:1", "HTTP_PROXY": "http://127.0.0.1:1", "no_proxy": "", "NO_PROXY": ""}):
+            code, _, _ = self.run_cli("info")
+        self.assertEqual(code, 0)
+        self.assertEqual(len(self.server.calls), 1)
+
+    def test_bad_json_and_shape(self):
+        for payload in (b"", b"<html>not the API</html>", b"\xff", b"null", b"42", b'"string"'):
+            self.server.payload = payload
+            code, out, err = self.run_cli("info")
+            self.assertEqual((code, out), (1, ""))
+            self.assertIn("JSON", err)
+
+    def test_response_limit(self):
+        with patch("bofile.client.MAX_RESPONSE", 8):
+            code, _, err = self.run_cli("info")
+        self.assertEqual(code, 1)
+        self.assertIn("exceeds", err)
+
+    def test_connection_error_and_timeout_no_retry(self):
+        from http.client import IncompleteRead
+        from urllib.error import URLError
+        client = Client(self.base)
+        for error in (URLError("secret"), TimeoutError(), IncompleteRead(b"partial")):
+            with patch.object(client.opener, "open", side_effect=error) as opened:
+                with self.assertRaises(BofileError) as caught:
+                    client.request("/api/info")
+                self.assertNotIn("secret", str(caught.exception))
+                self.assertEqual(opened.call_count, 1)
+
+    def test_invalid_routes_are_rejected(self):
+        for path in ("https://evil.example/api/info", "//evil.example", "/api/info?x=y", "/api/../info"):
+            with self.assertRaises(BofileError):
+                Client(self.base).request(path)
+        self.assertEqual(self.server.calls, [])
+
+    def test_parser_rejections_do_not_send(self):
+        cases = [("transfer", "cancel", "0"), ("transfer", "resume", "-1"),
+                 ("transfer", "download", "p", "file", "."),
+                 ("transfer", "download", "p", "file", ".", "--size", "-1"),
+                 ("transfer", "cancel", str(2**63)), ("message", "send", "p", " "),
+                 ("info", "--timeout", "nan"), ("info", "--timeout", "0")]
+        for args in cases:
+            with contextlib.redirect_stderr(io.StringIO()):
+                with self.assertRaises(SystemExit) as caught:
+                    self.run_cli(*args)
+            self.assertEqual(caught.exception.code, 2)
+        self.assertEqual(self.server.calls, [])
+
+
+class URLTests(unittest.TestCase):
+    def test_numeric_loopback_only(self):
+        for value, port in (("http://127.0.0.1:34120", 34120),
+                            ("http://[::1]:34120/", 34120), ("https://127.0.0.1", 443)):
+            with self.subTest(value=value):
+                self.assertEqual(validate_base_url(value), (value.rstrip("/"), port))
+        for value in ("http://localhost:34120", "http://evil.example", "http://192.168.1.1",
+                      "http://0.0.0.0", "file:///tmp/token", "http://127.0.0.1@evil.example",
+                      "http://user:pass@127.0.0.1", "http://127.0.0.1/api/info",
+                      "http://127.0.0.1?x=1", "http://127.0.0.1#frag", "http://127.0.0.1?",
+                      "http://127.0.0.1#", "http://127.0.0.1:", "http://127.0.0.1:0",
+                      "http://127.0.0.1:65536", "http://2130706433", "http://127.1",
+                      "http://[::ffff:127.0.0.1]", "http://[::1%25lo0]", "\nhttp://127.0.0.1"):
+            with self.subTest(value=value):
+                with self.assertRaises(BofileError):
+                    validate_base_url(value)
+
+
+if __name__ == "__main__":
+    unittest.main()