Metadata-Version: 2.5
Name: rcode-agent
Version: 0.1.0
Summary: RCode tunnel agent: exposes a local port at a public HTTPS hostname.
Requires-Python: >=3.11
Requires-Dist: click>=8.2
Requires-Dist: httpx>=0.27
Requires-Dist: rcode-tunnel
Requires-Dist: websockets>=13
Description-Content-Type: text/markdown

# rcode-agent

The RCode tunnel agent. Exposes a port on this machine at a public HTTPS
hostname and manages that tunnel's access control.

```bash
rcode-agent login                      # store relay url, gateway url, token
rcode-agent http 3000 --subdomain demo # forward https://demo.t.example.com
rcode-agent codes create demo --expires 24h --uses 5 --label press
rcode-agent codes list demo
rcode-agent codes revoke demo 5
rcode-agent link create demo --expires 1h
rcode-agent link rotate demo
rcode-agent access set demo --mode allowlist --email a@b.com
rcode-agent tunnels list
```

Configuration comes from `RCODE_TOKEN`, `RCODE_RELAY_URL`, and `RCODE_API_URL`,
falling back to `~/.config/rcode/config.toml` (`%APPDATA%/rcode/config.toml` on
Windows), which `login` writes with mode 0600. Set `RCODE_CONFIG` to point at a
different file.

`rcode-agent http` logs at INFO by default; pass `--verbose` for DEBUG
(per-stream detail). A local dial that fails is reported once as a WARNING
("Is the local service running?"), not once per request, and warns again the
next time it fails after a successful dial in between.

Design: `docs/superpowers/specs/2026-09-15-tunnel-service-design.md`, section 10.

## Security notes

- The config file written by `login` is created with mode `0600` (owner
  read/write only). On Windows this is a best-effort request: the file is
  opened with the POSIX create mode, but the enforced access control comes
  from Windows ACLs (typically already restricted to the owning user's
  profile), not from the mode bits.
- The account token is never printed or logged by the CLI. `login` prompts
  for it with `hide_input=True`, and no command echoes the resolved
  configuration (including the token) back to the terminal. Error messages
  raised as `click.ClickException` never include the token.
- A static scanner may flag `config_path()` for "path traversal" because it
  builds a filesystem path from the `RCODE_CONFIG` and `APPDATA` environment
  variables. This is a known, accepted false positive: `rcode-agent` is a
  local command-line tool, and its own process environment is
  operator-trust-level input, not untrusted request data. There is no
  attacker-controlled input path into `config_path()`.
