snulbug 0.2.3__tar.gz → 0.2.5__tar.gz

{snulbug-0.2.3 → snulbug-0.2.5}/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on Keep a Changelog, and this project follows semantic versi
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-10-23
+
+Public-origin preservation for shared MCP and HTTP gateways.
+Read the [0.2.5 upgrade notes](docs/upgrading-to-0.2.5.md) before deploying an
+existing ngrok share or a share with required signed HTTP mount contracts.
+
+- Forward canonical public host, scheme, and port from the configured share URL across internal hops. HTTP mounts can opt into `preserve_host = true`; backend Host remains the default and upstream TLS verification is unchanged.
+- Generate ngrok policies that capture and validate the original public authority/scheme before forwarding and replace caller-supplied origin/audit headers. Reject invalid capture pairs at the gateway and unsafe public URLs at config load; keep observed ingress headers for audit provenance, not forwarding authority.
+- Include effective origin and Host mode in mount health checks, doctor, status, reports, the web console, readiness reviews, and signed mount contracts. Existing ngrok policies need manual review and reattachment; no cloud changes or share regeneration are applied automatically.
+- Add regression coverage for spoofed/duplicate headers, redirects, prefixes, ports, IPv6, MCP forwarding, health/cache invalidation, and contract drift, including installed-wheel packaging checks.
+
+No change to the default MCP protocol or preview limitations. Application auth,
+proxy trust, base paths, and CSRF defenses remain the mounted app's responsibility;
+this release does not rewrite HTML, redirect locations, or cookie paths.
+
+## [0.2.4] - 2026-10-19
+
+Operational hardening for always-on shares and shared HTTP/MCP gateways.
+See the [0.2.4 upgrade notes](docs/upgrading-to-0.2.4.md) before restarting an
+existing service, especially if a tunnel is already running separately.
+
+- Moved ngrok/SSH tunnel management into the share runtime: `share run` supervises tunnels with or without the web console, bounded crash-restart backoff, explicit stop/start controls, and graceful gateway/tunnel shutdown. Added `--no-tunnel` and always-on deployment recipes.
+- Added read-only ngrok policy drift checks to share doctor, readiness, reports, and the console: compare current config, generated policy, and deployed Cloud Endpoint policy without exposing deployed secrets or applying cloud changes. Includes OAuth-aware edge baselines and stale-result invalidation.
+- Added evidence-based request failure explanations to existing audit logs, live decisions, and session reports: distinguish admission gates, upstream credentials/connectivity, HTTP/MCP errors, partial catalogs, and response checks while preserving Lua decisions and unknown execution outcomes. Removed raw forwarding exceptions from client errors and facade health evidence; no tool-call retries.
+- Hardened upstream credential operations: bounded regular-file/header reads, secret-free broker failures, and live share doctor availability/hygiene checks surfaced in readiness, status, reports, and the Auth drawer. Documented atomic file rotation and environment restart semantics; passive refreshes reuse saved diagnostics without resolving secrets.
+- Added explicit HTTP mount contracts for authentication ownership, methods, credential-header forwarding, inactivity timeouts, and optional backend health checks. Reused share doctor/readiness, reports, the provider drawer, and signed share-contract bindings; public mounts strip Authorization/cookies by default, and MCP auth/leases remain separate from application access.
+- Added isolated installed-wheel operations QA for share creation, local MCP/HTTP traffic, credential rotation, persisted leases, and supervised shutdown. Fixed installed-package share creation so container recipe snapshots no longer require a source checkout.
+
+No change to the default MCP protocol version or experimental profile limitations.
+This release does not add HTTP application OIDC, overload protection, automatic
+tool-call retries, or a published container image.
+
 ## [0.2.3] - 2026-10-18
 
 Add Pocket ID setup through the existing OAuth provider and lease machinery.

{snulbug-0.2.3 → snulbug-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: snulbug
-Version: 0.2.3
+Version: 0.2.5
 Summary: A local-dev MCP policy proxy with Lua policies, replay logs, and learned least-privilege bundles
 Project-URL: Homepage, https://github.com/nahuaque/snulbug
 Project-URL: Repository, https://github.com/nahuaque/snulbug
@@ -174,7 +174,12 @@ snulbug mcp share run .snulbug/shares/share-...
 Inside a generated share directory, `snulbug mcp share run` is enough;
 it reads `.snulbug/share/session.json`, reconciles the active config,
 policy, lease, and log paths, and starts the local share console before
-starting the gateway. Pass `--no-console` when you only want the proxy.
+starting the gateway. Pass `--no-console` to disable the local web UI.
+
+For ngrok and SSH shares, `share run` also starts and supervises the generated
+tunnel independently of the console. Use `--no-tunnel` for an externally managed
+agent. See [always-on deployment](docs/always-on-runtime.md) for crash recovery,
+graceful shutdown, and systemd, launchd, and container recipes.
 
 3. Check what is happening:
 

{snulbug-0.2.3 → snulbug-0.2.5}/README.md

@@ -131,7 +131,12 @@ snulbug mcp share run .snulbug/shares/share-...
 Inside a generated share directory, `snulbug mcp share run` is enough;
 it reads `.snulbug/share/session.json`, reconciles the active config,
 policy, lease, and log paths, and starts the local share console before
-starting the gateway. Pass `--no-console` when you only want the proxy.
+starting the gateway. Pass `--no-console` to disable the local web UI.
+
+For ngrok and SSH shares, `share run` also starts and supervises the generated
+tunnel independently of the console. Use `--no-tunnel` for an externally managed
+agent. See [always-on deployment](docs/always-on-runtime.md) for crash recovery,
+graceful shutdown, and systemd, launchd, and container recipes.
 
 3. Check what is happening:
 

{snulbug-0.2.3 → snulbug-0.2.5}/docs/README.md

@@ -29,6 +29,7 @@ share create -> share run -> share status -> share requests approve -> share pol
 ## Sharing, Tunnels, And Remote Dev
 
 - [End-to-end ngrok MCP gateway](ngrok-end-to-end.md)
+- [Always-on share runtime and deployment](always-on-runtime.md)
 - [Tunnel provider plugins](tunnel-providers.md)
 - [Credential broker plugins](credential-brokers.md)
 - [Discovery provider plugins](discovery-providers.md)

snulbug-0.2.5/docs/always-on-runtime.md

@@ -0,0 +1,385 @@
+# Always-on share runtime
+
+Use the existing `snulbug mcp share run DIRECTORY` command for a long-lived
+gateway. It runs in the foreground; systemd, launchd, or a container restart
+policy owns whole-gateway restarts. There is no separate daemon or new CLI.
+Create and review the share first using [MCP share sessions](mcp-share.md).
+
+## Tunnel ownership
+
+For ngrok and SSH shares, `share run` automatically starts and supervises the
+managed tunnel independently of the web console. It uses the same generated
+provider config and commands; existing shares need no new generated layout.
+ngrok still uses `tunnel/ngrok-agent.yml` plus the separately attached Cloud
+Endpoint Traffic Policy. SSH still uses the generated reverse-forward target.
+See the [ngrok walkthrough](ngrok-end-to-end.md) for cloud setup.
+
+```bash
+/opt/snulbug/venv/bin/snulbug mcp share run /var/lib/snulbug/share --no-console
+```
+
+- `--no-console` disables only the UI, not tunnel startup or supervision.
+- `--no-tunnel` disables automatic tunnel startup. The console can still
+  explicitly start a managed tunnel; combine both flags for a headless gateway
+  whose tunnel is externally managed.
+- The existing console **Start tunnel** and **Stop tunnel** controls operate on
+  the same managed process. An intentional stop cancels pending restarts and
+  keeps the tunnel stopped until an explicit start.
+- `generic`, `cloudflare`, `tailscale`, `pinggy`, `holepunch`, and other supported
+  providers remain externally managed. Their generated setup commands still
+  apply; snulbug does not start, restart, or stop those external processes.
+
+Do not start a second provider process for an automatically managed endpoint.
+The runtime supervises processes, not public reachability: a running ngrok or
+SSH process does not prove that forwarding, DNS, TLS, authentication, or cloud
+policy is correct. Use existing share doctor and health checks, including the
+public URL checks, rather than treating a PID as readiness.
+For ngrok, [doctor's policy drift inspection](ngrok-end-to-end.md#check-for-configuration-drift)
+compares local configuration with the deployed Cloud Endpoint through optional,
+read-only API access. Supply its API credential to the service account to enable
+the same inspection from the console; it is separate from the agent authtoken.
+
+## Runtime settings
+
+The following optional table in the share's existing `snulbug.toml` shows all
+defaults. Merge it into the file; do not replace the generated config or add a
+second `[mcp.runtime]` table. Durations are in seconds.
+
+```toml
+[mcp.runtime]
+tunnel_autostart = true
+restart_initial_seconds = 1.0
+restart_max_seconds = 30.0
+restart_max_attempts = 5
+restart_reset_seconds = 60.0
+tunnel_shutdown_timeout = 5.0
+graceful_shutdown_timeout = 30.0
+```
+
+`tunnel_autostart = false` disables automatic startup in the same way as
+`--no-tunnel`; an explicit console start remains available. `--no-tunnel`
+overrides `tunnel_autostart = true` for that invocation.
+
+An unexpected managed tunnel exit triggers bounded exponential crash restart:
+the delay begins at `restart_initial_seconds`, doubles on each retry, and is
+capped at `restart_max_seconds`. `restart_max_attempts` limits restart attempts,
+not the initial launch. With defaults, a repeatedly crashing process gets at
+most five retries, after delays of 1, 2, 4, 8, and 16 seconds.
+
+After exhaustion, automatic retries stop. Fix the cause, then explicitly start
+the tunnel through the console or restart the whole service. A healthy process
+running continuously for `restart_reset_seconds` resets the retry budget; this
+is process stability, not a successful public endpoint probe. An intentional
+console stop is not a crash and never consumes a retry or triggers a restart.
+
+Only the managed tunnel process is restarted here. The OS supervisor handles a
+gateway process failure; it is not a public health watchdog and should not be
+used to bypass exhausted tunnel retries. No MCP tool calls are retried or
+replayed by this runtime. A broken connection can leave a tool's outcome
+unknown; reconnecting does not make a repeated side effect safe.
+The existing decision feed and session reports include
+[request failure explanations](mcp-evidence.md#request-failure-explanations),
+separating admission, upstream credentials/transport, and response-policy failures
+without performing retries or adding background probes.
+
+## Shutdown
+
+On SIGTERM or SIGINT, Uvicorn stops accepting new work and drains in-flight
+requests and streams. `graceful_shutdown_timeout` bounds that drain; at the
+deadline, remaining work is cancelled. Only after the gateway drain/cancellation
+does the runtime stop its managed tunnel. `tunnel_shutdown_timeout` bounds the
+tunnel's termination wait before forced cleanup. Tunnel restart is suppressed
+during shutdown. Externally managed provider processes remain their owner's
+responsibility.
+
+Give the outer supervisor more than the sum of these two timeouts plus cleanup
+headroom. The recipes below use 45 seconds for the default 30-second drain and
+5-second tunnel wait. Increase the supervisor timeout if you increase either
+runtime setting. SIGKILL, a host crash, or a shorter supervisor deadline cannot
+provide graceful draining.
+
+## Deployment prerequisites
+
+- Install a build containing this runtime into a fixed virtual environment.
+  Use an absolute `snulbug` executable path, not an interactive shell's alias,
+  `uv run`, or a login-shell activation script. Keep the installation and
+  launcher files administrator-owned and non-service-writable.
+- Use a dedicated unprivileged account. Create the share once at its persistent
+  absolute path under that account; do not run `share create --force` at boot.
+  Keep the same path inside a container, or reconcile recorded paths before
+  moving an existing share.
+- Persist the whole share directory: config, policy, `leases.json`, invite
+  secrets, canonical session state, tunnel config, and evidence. Give the service
+  account write access, restrict the directory to mode `0700`, and protect
+  secret-bearing files with mode `0600`. Backups are secret-bearing too.
+- Install `ngrok` or `ssh` on the service's explicit `PATH`. Complete ngrok's
+  generated authtoken setup; a placeholder config will not start. For SSH,
+  provision non-interactive credentials and verified `known_hosts` for that
+  account. Do not disable host-key verification or depend on a desktop agent.
+- Arrange the upstream service separately. A tunnel restart does not restart
+  the upstream, renew expired leases, extend invite authorization, or repair
+  cloud policy. Use [renewable automation invites](mcp-share.md#renewable-automation-invites)
+  where a bot needs approved renewal rather than an unbounded lease.
+- Keep the share console on loopback or disable it with `--no-console`, as these
+  recipes do. Never add a public tunnel or shared HTTP route to its admin port
+  or ngrok's inspection port. For remote administration, deliberately enable
+  the loopback console and use authenticated SSH local forwarding.
+
+Do not put tokens in unit files, plists, command arguments, images, or source
+control. Where the generated configuration uses environment references, load
+them from a protected env file. For example, `share.env` can contain:
+
+```dotenv
+SNULBUG_SHARE_TOKEN=replace-with-the-existing-share-token
+```
+
+This is an existing credential, not a request to mint a different token. Keep
+secrets already stored in generated policy/provider files protected as well;
+setting an env variable does not replace a literal ngrok authtoken placeholder.
+Environment variables are still visible to sufficiently privileged local
+processes. Treat service logs and container inspection access as sensitive.
+
+For upstream service tokens, prefer the existing
+[credential broker references](credential-brokers.md#always-on-upstream-credentials).
+File sources support atomic replacement without a restart; environment-backed
+sources require a service restart to pick up supervisor environment changes.
+Live share doctor checks availability and hygiene, and status/report plus the
+console's Auth drawer reuse its secret-free diagnostics. Run checks in the
+service environment: local availability is not proof of upstream acceptance.
+
+If the same tunnel exposes a web app or API, declare its
+[HTTP mount contract](mcp-proxy.md#mount-contracts-and-readiness): explicit
+auth ownership, methods, credential-header forwarding, and an optional safe
+backend health endpoint. MCP lease revocation does not stop application access.
+Use the existing share doctor and provider drawer to review both kinds of
+exposure; application OIDC/session auth remains the app's responsibility.
+
+## Linux: systemd
+
+This example assumes an existing `snulbug` user/group, an installation at
+`/opt/snulbug/venv`, and a share created at `/var/lib/snulbug/share`.
+Store the env file at `/etc/snulbug/share.env`, owned by root with mode `0600`;
+systemd reads it before dropping privileges. Install ngrok at
+`/usr/local/bin/ngrok` or SSH at `/usr/bin/ssh`.
+
+Install `/etc/systemd/system/snulbug-share.service`:
+
+```ini
+[Unit]
+Description=snulbug MCP share gateway
+Wants=network-online.target
+After=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=exec
+User=snulbug
+Group=snulbug
+WorkingDirectory=/var/lib/snulbug/share
+Environment=HOME=/var/lib/snulbug
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+EnvironmentFile=/etc/snulbug/share.env
+ExecStart=/opt/snulbug/venv/bin/snulbug mcp share run /var/lib/snulbug/share --no-console
+Restart=on-failure
+RestartSec=5s
+KillSignal=SIGTERM
+KillMode=mixed
+TimeoutStopSec=45s
+UMask=0077
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+`KillMode=mixed` sends the initial SIGTERM to the gateway, allowing it to drain
+before stopping its tunnel; leftover processes are still forcibly cleaned up.
+The default control-group termination would signal the tunnel at the same time
+as the gateway. See [systemd.kill](https://www.freedesktop.org/software/systemd/man/latest/systemd.kill.html).
+`Restart=on-failure` covers gateway failure, not tunnel retry exhaustion or an
+intentional service stop. See [systemd.service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html).
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now snulbug-share.service
+sudo journalctl -u snulbug-share.service -f
+```
+
+Stop with `sudo systemctl stop snulbug-share.service`. After repairing a gateway
+start failure that hit systemd's start limit, use `sudo systemctl reset-failed
+snulbug-share.service`, then `sudo systemctl start snulbug-share.service`.
+Use `sudo systemctl restart snulbug-share.service` for an explicit whole-service
+restart, including recovery after exhausted tunnel retries.
+
+## macOS: launchd
+
+For service operation before login, use a LaunchDaemon, not a per-login
+LaunchAgent. This example assumes an existing dedicated `snulbug` account/group
+with home `/Users/snulbug`, an installation at `/opt/snulbug/venv`, and a share
+at `/Users/snulbug/share`. Create `/Users/snulbug/Library/Logs/snulbug` for its
+logs, owned by that account with mode `0700`. The machine must remain awake and
+its share volume must be available; launchd cannot provide uptime during sleep.
+See Apple's [launchd job guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html).
+
+launchd has no systemd-style `EnvironmentFile`. Store
+`/Users/snulbug/.config/snulbug/share.env` as mode `0600`, owned by `snulbug`,
+inside mode `0700` directories. Use simple shell-compatible `KEY=value` entries
+with quoted values where needed. The following root-owned, non-service-writable
+launcher at `/usr/local/libexec/snulbug-share-run` only loads that trusted file
+and replaces itself with the existing command; it is not a new daemon:
+
+```sh
+#!/bin/sh
+set -eu
+umask 077
+set -a
+. /Users/snulbug/.config/snulbug/share.env
+set +a
+export HOME=/Users/snulbug
+export PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin
+exec /opt/snulbug/venv/bin/snulbug mcp share run /Users/snulbug/share --no-console
+```
+
+Install `/Library/LaunchDaemons/com.snulbug.share.plist`, owned by `root:wheel`
+with mode `0644`; keep secrets out of it:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.snulbug.share</string>
+  <key>UserName</key>
+  <string>snulbug</string>
+  <key>GroupName</key>
+  <string>snulbug</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/libexec/snulbug-share-run</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>/Users/snulbug/share</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ExitTimeOut</key>
+  <integer>45</integer>
+  <key>StandardOutPath</key>
+  <string>/Users/snulbug/Library/Logs/snulbug/share.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/Users/snulbug/Library/Logs/snulbug/share.err.log</string>
+</dict>
+</plist>
+```
+
+`KeepAlive` restarts a gateway that exits; `ThrottleInterval` limits rapid
+launches, and `ExitTimeOut` leaves time for graceful shutdown. These are outer
+process controls, not public health checks or the managed tunnel retry budget.
+See Apple's [launchd.plist reference](https://github.com/apple-oss-distributions/launchd/blob/main/man/launchd.plist.5).
+
+```bash
+sudo chmod 0755 /usr/local/libexec/snulbug-share-run
+plutil -lint /Library/LaunchDaemons/com.snulbug.share.plist
+sudo launchctl bootstrap system /Library/LaunchDaemons/com.snulbug.share.plist
+sudo launchctl print system/com.snulbug.share
+```
+
+For an orderly stop, use `sudo launchctl bootout system/com.snulbug.share`.
+For an explicit restart, boot out, then bootstrap the plist again. Avoid
+`launchctl kickstart -k` for a draining restart: it kills the existing process.
+A direct signal while `KeepAlive` is enabled may cause a new gateway launch;
+boot out to keep the service stopped. Arrange rotation for the log files.
+
+## Container
+
+Use a locally built image containing this runtime and the chosen provider
+binary; no new published image is required. The generated
+`containers/Dockerfile.gateway` is a starting point and installs from its
+`snulbug-src/` snapshot of the checkout or installed package, not a published
+snulbug image. Ensure that snapshot
+contains the runtime. It does not install ngrok or SSH: add a verified,
+architecture-matched Linux ngrok binary or install `openssh-client` in your
+local build before using managed startup. Never copy provider credentials into
+the image. In this example the resulting local tag is
+`snulbug-share-runtime:local`, and snulbug is installed at
+`/usr/local/bin/snulbug` with provider binaries on its `PATH`.
+
+The following command is for a Linux Docker host. Create the share at
+`/srv/snulbug/share` and keep its generated gateway bound to `127.0.0.1`.
+Host networking lets the gateway and its managed tunnel use the existing
+loopback origin and reach an upstream on the host's loopback interface without
+changing generated tunnel config. Do not use this unchanged for Docker Desktop
+or bridge networking; those require deliberate upstream/network configuration.
+The example assumes the host service account has UID/GID `10001:10001` and owns
+the persistent share; substitute your account's numeric IDs.
+
+Protect `/etc/snulbug/share.env` on the host as root-owned with mode `0600`.
+Use Docker's `KEY=value` env-file syntax, not shell `export` or shell expansion.
+The privileged Docker invocation below can read that file; the container itself
+runs as the unprivileged UID. Use a persistent read-write bind volume at the
+same absolute path:
+
+```bash
+sudo docker run --detach --name snulbug-share \
+  --pull=never \
+  --init \
+  --restart=unless-stopped \
+  --stop-signal=SIGTERM \
+  --stop-timeout=45 \
+  --network=host \
+  --user=10001:10001 \
+  --env-file=/etc/snulbug/share.env \
+  --env HOME=/srv/snulbug \
+  --env PATH=/usr/local/bin:/usr/bin:/bin \
+  --mount type=bind,src=/srv/snulbug/share,dst=/srv/snulbug/share \
+  --workdir=/srv/snulbug/share \
+  --entrypoint=/usr/local/bin/snulbug \
+  snulbug-share-runtime:local \
+  mcp share run /srv/snulbug/share --no-console
+```
+
+For SSH, also mount the service account's SSH config, private key, and verified
+`known_hosts` read-only at `/srv/snulbug/.ssh`, with permissions readable only by
+that UID. Do not mount a general-purpose personal SSH directory. For ngrok,
+complete the authtoken configuration in the protected share volume.
+
+`--init` forwards signals and reaps children; `--stop-timeout` allows draining
+before forced termination. No console or inspection port is published. With
+host networking, loopback binds are essential: it does not isolate listening
+ports from the host. See [Docker run reference](https://docs.docker.com/reference/cli/docker/container/run/).
+
+Use `sudo docker logs -f snulbug-share` for gateway output and
+`sudo docker stop snulbug-share` for an orderly stop. Use
+`sudo docker restart --timeout 45 snulbug-share` for an explicit restart. The
+restart policy handles container exit, not a live gateway with exhausted tunnel
+retries or failing public checks.
+
+## Verify and operate
+
+After starting or restarting, use the existing checks from an account and
+network that can reach the intended client URL:
+
+```bash
+/opt/snulbug/venv/bin/snulbug mcp share status /var/lib/snulbug/share
+/opt/snulbug/venv/bin/snulbug mcp share doctor /var/lib/snulbug/share \
+  --url https://YOUR-PUBLIC-HOST/mcp
+```
+
+Use the corresponding paths on macOS or inside the container. An SSH share's
+default client URL is loopback on the remote SSH host, not the gateway host;
+verify from that remote side as described in
+[plain SSH reverse tunnels](mcp-share.md#plain-ssh-reverse-tunnel). For ngrok,
+verify the generated Traffic Policy is attached to the public Cloud Endpoint,
+not just that the private internal Agent Endpoint is running.
+
+If a tunnel repeatedly exits, inspect its existing console diagnostics and
+provider log, fix credentials/configuration or duplicate agents, and explicitly
+start it again. With `--no-console`, restart the OS service instead. Do not
+automatically replay failed MCP tool calls as a recovery mechanism. Finish a
+bounded sharing task with the existing [closeout flow](mcp-share.md#close-out);
+stopping a process alone is not lease or invite revocation.

snulbug-0.2.5/docs/credential-brokers.md

@@ -0,0 +1,172 @@
+# Credential broker plugins
+
+snulbug uses credential brokers to inject upstream credentials without
+forwarding caller tokens. Built-ins support:
+
+- `type = "env"`: read the secret from an environment variable
+- `type = "file"`: read the secret from a local file
+
+External brokers can add other sources such as a local keychain, a vault, a
+container metadata service, or a short-lived token minting service.
+
+## Always-on upstream credentials
+
+Keep caller authentication and upstream credentials separate. A client's OAuth
+token or share bearer authenticates to snulbug; an upstream credential reference
+authenticates snulbug to that upstream. Missing upstream credentials fail closed,
+without retrying a tool call, forwarding the caller's token as a fallback, or
+reusing a previously resolved value.
+
+Use the existing registry in the share's `snulbug.toml`. File paths are relative
+to that config file, not the launcher's working directory:
+
+```toml
+[mcp.fabric.credentials.service]
+type = "file"
+path = "/run/secrets/mcp-service-token"
+scheme = "bearer"
+header = "Authorization"
+
+[mcp.proxy]
+upstream = "https://mcp.example.com/mcp"
+upstream_credential = "service"
+```
+
+Merge the setting into the existing `[mcp.proxy]` table rather than adding a
+duplicate. For a facade, attach `auth = "service"` to the relevant
+`[[mcp.proxy.upstreams]]` entry instead. Do not store secret values in TOML,
+command arguments, images, or the policy source.
+
+### Check and inspect
+
+```bash
+snulbug mcp share doctor /var/lib/snulbug/share
+snulbug mcp share status /var/lib/snulbug/share
+snulbug mcp share report /var/lib/snulbug/share
+```
+
+Doctor's `credentials` check resolves each used source once and adds
+`upstream_credentials` to its JSON result. It reports missing/unreadable,
+empty, malformed, or oversized values as failures. It warns about POSIX
+group/other file permissions, credentials sent over non-loopback plain HTTP,
+client Authorization passthrough, and HTTP credential references on stdio
+transports. Hygiene warnings require review, not an automatic chmod or config
+rewrite. Intentional private Docker networks may explain an HTTP warning;
+snulbug cannot prove that such a network is private.
+
+The console's **Auth** section has an **Upstream credentials** drawer with
+source references, attached upstreams, last-check state, rotation guidance,
+and the existing **Run doctor** action. Readiness fails for a recorded source
+failure and requests review for unchecked, changed, or warning states. No
+additional credential-management endpoint or secret-reveal control is added.
+
+Offline doctor skips source resolution. Status, reports, and normal console
+refreshes reuse saved diagnostics, never invoke brokers, and never record
+secret values or hashes of them. A reference, route, or file stat change
+invalidates saved availability and requires another doctor run. The input
+digest covers references and file metadata only; it is not a secret fingerprint.
+Doctor results are historical diagnostics, not an authorization decision or a
+guarantee about the next request. The request path always resolves again.
+
+Availability means **resolved in the checking process**, not accepted by the
+upstream. Run doctor with the same service account and environment as the
+gateway, or use the running console's action. A CLI process may have different
+environment values or permissions. Opaque token expiry, revocation, audience,
+and upstream privileges cannot be inferred from a successful local read; use
+the existing health checks and request failure explanations to see upstream
+401/403 responses.
+
+### Rotation
+
+- **File:** stage the new value in a protected file on the same filesystem,
+  set its service ownership and mode (`0600` or a deliberate read-only mode),
+  then atomically rename it over the referenced path. New requests read the
+  replacement without a gateway restart. Do not truncate/rewrite the live file.
+  Symlinks to regular files are supported, including projected container
+  secrets. A missing or invalid replacement fails new requests immediately.
+- **Environment:** update the supervisor's protected environment file and
+  restart the gateway. Exporting a variable in another shell cannot modify a
+  running process's environment. There is no last-known-good cache to flush.
+- **Plugin:** the broker owns its source-specific refresh and rotation policy.
+  Keep network resolution bounded; plugins run trusted Python code and snulbug
+  does not supply a universal vault timeout or refresh scheduler.
+
+File sources must resolve to regular UTF-8 files, at most 16 KiB, with an
+optional trailing newline. Nonregular sources (including FIFOs/devices) are
+rejected before reading. Every broker's result must be a nonempty, bounded
+single HTTP header value without control characters. Resolver exception text
+is replaced with fixed diagnostics, including for plugin errors.
+POSIX mode checks inspect the target file, not directory permissions, ACLs,
+ownership, or Windows access controls; restrict those separately as part of
+service provisioning.
+
+Rotation applies at request/probe boundaries. An established SSE stream or
+managed upstream session is not reauthenticated mid-flight. Arrange upstream
+old/new-token overlap when needed; snulbug does not retry rejected calls or
+guess whether side effects occurred. After replacement, run doctor again and
+verify a safe client operation before revoking the old token upstream.
+
+This check covers credentials attached to MCP HTTP/Holepunch upstreams. It does
+not rotate client share bearers, invite renewal secrets, OAuth signing keys,
+ngrok agent authtokens, SSH keys, or mounted applications' sessions. Keep using
+their existing controls. HTTP mounts remain outside the MCP credential broker.
+
+## Custom brokers
+
+```python
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from snulbug import CredentialBroker, register_credential_broker
+
+
+class AcmeVaultBroker(CredentialBroker):
+    type = "acme-vault"
+
+    def normalize_source(
+        self,
+        entry: Mapping[str, Any],
+        *,
+        base_dir: Path,
+        field: str,
+        resolve_relative_paths: bool,
+    ) -> Mapping[str, Any]:
+        del base_dir, resolve_relative_paths
+        name = entry.get("name")
+        if not isinstance(name, str) or not name:
+            raise ValueError(f"{field}.name must be a non-empty credential name")
+        return {"name": name}
+
+    def resolve(self, credential: Mapping[str, Any]) -> str:
+        # Fetch or mint the secret here. Return the raw token value; snulbug
+        # applies the configured scheme before forwarding.
+        return fetch_from_acme_vault(str(credential["name"]))
+
+    def metadata(self, credential: Mapping[str, Any]) -> Mapping[str, Any]:
+        # Return only audit-safe fields. Never return the resolved secret.
+        return {"name": credential.get("name")}
+
+
+register_credential_broker(AcmeVaultBroker(), replace=True)
+```
+
+Config uses the same `[mcp.fabric.credentials]` table as built-ins:
+
+```toml
+[mcp.fabric.credentials.codespace]
+type = "acme-vault"
+name = "codespace-mcp-token"
+scheme = "bearer"
+header = "Authorization"
+
+[[mcp.proxy.upstreams]]
+name = "codespace-files"
+url = "https://example-codespace.github.dev/mcp"
+auth = "codespace"
+```
+
+The broker is called when snulbug forwards a request, probes an upstream, or
+explicitly checks its availability through live doctor/fabric diagnostics.
+Audit logs, share contracts, fabric status, and replay logs receive only
+`credential_metadata()` output.

{snulbug-0.2.3 → snulbug-0.2.5}/docs/devcontainers.md

@@ -10,8 +10,8 @@ servers with a shared control plane.
 ```json
 {
   "features": {
-    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.3": {
-      "version": "0.2.3",
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.5": {
+      "version": "0.2.5",
       "mode": "member-agent",
       "policy_profile": "tunnel-safe",
       "registry": "redis://redis:6379/0",