Metadata-Version: 2.4
Name: sitecard
Version: 0.1.2
Summary: Issue temporary SSH access cards for development workspaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: asyncssh==2.24.0
Requires-Dist: cryptography>=39
Requires-Dist: websockets

# Sitecard

Issue temporary SSH access cards for development sites and workspaces.

This directory holds only the static sanitized README staged into the
generated `sitecard` distribution. The distributable package itself is
generated by `scripts/build-sitecard-dist.sh` and never checked in.

## What it is

Sitecard opens temporary SSH access to a selected development workspace for
remote debugging and compatibility testing. The site is the workspace host;
the card is the short-lived access path. Fresh Sitecard sessions allow public
access by default because they are disposable. Pass `--no-public-access` to
require credentials.

- Distribution name: `sitecard`
- Version: `0.1.2`
- Description: `Issue temporary SSH access cards for development workspaces`
- Requires Python `>=3.10`
- Console script: `sitecard = sitecard.commands:main`

## What it is not

The generated distribution contains no deployment helpers, local secrets,
target addresses, assessment keys, tests, or unrelated files.

## Build

From the repository root:

```sh
sh scripts/build-sitecard-dist.sh
```

Artifacts land in `dist/sitecard/`. The build fails if any
case-insensitive occurrence of the internal project name remains in
staging files, archive entry names, or archive file contents.

## Authenticated access (`--no-public-access`)

Public mode is the default and needs no keys.

For `--no-public-access` with a non-Upterm provider, provision two
operator-supplied public key files inside Sitecard state (the
pre-existing `0700` state directory: `$SITECARD_STATE_DIR/sitecard`
when `SITECARD_STATE_DIR` is set, otherwise
`$XDG_STATE_HOME/sitecard`, falling back to
`$HOME/.local/state/sitecard`):

```sh
STATE="${SITECARD_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}}/sitecard"
umask 077
mkdir -p "$STATE"
chmod 700 "$STATE"
printf '%s\n' 'ssh-ed25519 AAAA...primary-operator-key primary' > "$STATE/authorized_keys"
printf '%s\n' 'ssh-ed25519 AAAA...distinct-recovery-key recovery' > "$STATE/recovery_authorized_keys"
chmod 600 "$STATE/authorized_keys" "$STATE/recovery_authorized_keys"
```

Rules:

- `authorized_keys` is the primary operator key file.
- `recovery_authorized_keys` is the independent recovery key file.
- Both files hold public keys only, mode `0600`, one OpenSSH public
  key per line.
- The recovery key must be a distinct operator-supplied public key.
  Never copy the primary key into the recovery file and never generate
  a private key the operator cannot access.
- Recovery is optional; when the file is absent or empty only the
  primary file is used.
- Recovery applies to authenticated non-Upterm transports only. It is
  not used with the upterm provider, which authenticates via
  relay-issued certificates.
- Authenticated non-Upterm sessions launch the gateway with
  `--authorized-keys <state>/authorized_keys` and
  `--recovery-authorized-keys <state>/recovery_authorized_keys`.
- Host SSH files such as `~/.ssh/authorized_keys` or the root host SSH
  file are never read or written for authenticated Sitecard sessions.

## Use

```sh
sitecard -h
sitecard serve --help
sitecard serve .
```

`serve` is a true alias of `start` with identical arguments.

## Dev Tunnel hosting

Install Microsoft's `devtunnel` CLI before starting. Sitecard does not download
tools, create tunnels, or change their access policies. Provision an existing
tunnel with port 4822 on an authenticated machine. Transfer a fresh host-scoped
token in a private file to the remote machine if it cannot perform OAuth login.
Keep the file mode `0600` and refresh it before expiry; restart rereads the file.

Run on the **remote workspace host**:

```sh
sitecard serve . --provider devtunnel --tunnel-id "$TUNNEL_ID" \
  --devtunnel-token-file "$HOST_TOKEN_FILE" --no-public-access
```

The token is passed to Dev Tunnel on stdin, not in argv or saved settings.
Only its file path is saved. Without the token-file option the CLI uses its
existing login. Sitecard starts a loopback SSH gateway first, then hosts the
existing tunnel without adding the already-configured port again. Startup
requires the hosting announcement, matching port, and local SSH banner.
The supervisor restarts failed children, subject to a bounded restart budget.
Status checks local gateway readiness, not end-to-end relay health.

Run on the **client**, keeping this process alive in a separate terminal:

```sh
devtunnel connect "$TUNNEL_ID"
```

Client port 4822 must be free. Do not also run a local Sitecard gateway or a
second tunnel client on that port. Use a connect-scoped token via
`--access-token -` if the client cannot log in. `sitecard connect` on the host
prints the client command and SSH instructions; its ProxyCommand needs `nc`
on the client. The public HTTPS URL is not a raw SSH endpoint. Hosting must
run where the workspace gateway lives, not on the client.

## Remote model proxy access

When a model works only through the remote machine's managed HTTP proxy,
copying a token does not reproduce that access. First test ordinary forwarding:

```sh
ssh -N -L 127.0.0.1:43706:127.0.0.1:43705 -p 4822 "$SSH_TARGET"
```

Replace the destination with the proxy address actually reachable from the
gateway. `--tcp-forwarding` enables this route; it is enabled by default.
Loopback refers to the gateway's network namespace, not another container's.
If a remote SSH command can reach the proxy but direct-TCP/IP forwarding
cannot, try the SSH exec fallback on the client:

```sh
sitecard forward "$SSH_TARGET" --ssh-port 4822 --listen-port 43706
```

This uses the remote SSH command's `HTTPS_PROXY`, connects there using existing
`python3`, and streams binary traffic over SSH stdin/stdout. No remote package
or CLI downloads are needed. Use `--proxy-env http_proxy` for a different
environment variable. It supports an `http://` proxy without URL credentials,
including HTTPS destinations via CONNECT. It does not support TLS-to-proxy or
SOCKS proxy URLs. SSH key authentication and a previously verified host key
are required because each connection uses noninteractive SSH. The local
listener is loopback-only; each connection opens one remote SSH command.

Point the model client at `http://127.0.0.1:43706` as its HTTP proxy, preserving
the original model endpoint URL and destination port. For clients honoring
environment variables, set `HTTPS_PROXY` and `HTTP_PROXY`; ensure `NO_PROXY`
does not bypass the intended destination. This forwards access, not credentials,
and does not change the model protocol or automate model requests. If Python
in the SSH exec context cannot reach the proxy either, this fallback cannot
cross that namespace boundary; run the gateway there or expose a reachable
proxy address. Do not publish the proxy as an anonymous public tunnel.
