feat(gastown): use container outbound handlers for provider API access

[jrf0110]

Summary

Give Gastown agents, especially town mayors, controlled power-tool access to provider APIs without exposing raw OAuth tokens in prompts, shell env, process args, or long-lived container state.

Instead of adding gt_get_fresh_token(...) as the primary path or injecting provider tokens into mayor context/env, use Cloudflare Container outbound handlers to intercept provider API requests and inject credentials from trusted Worker code outside the container sandbox.

Primary motivating use case: wasteland-connected towns need a way for the mayor to repair bad DoltHub/wasteland states, such as an in-review branch missing a completions row. The mayor should be able to use DoltHub APIs and SQL writes for doctoring, but the DoltHub OAuth token should not be visible to the model or shell.

Cloudflare docs: https://developers.cloudflare.com/containers/platform-details/outbound-traffic/

Proposed Design

Use outbound handlers on TownContainerDO for provider hosts:

• www.dolthub.com for DoltHub API and wasteland doctoring.
• api.github.com / github.com for GitHub API or Git HTTPS workflows if needed.
• GitLab hosts later.

Flow:

1. Agent/mayor runs a normal command, e.g. curl https://www.dolthub.com/api/v1alpha1/....
2. Cloudflare outbound handler intercepts the request.
3. Worker-side code resolves the container/town/agent context.
4. Worker-side code fetches or refreshes the relevant OAuth token from existing credential storage/services.
5. Handler injects Authorization: Bearer <token> and forwards the request.
6. Token never enters the container, model context, shell env, shell history, stdout, or process args.

The mayor-facing experience should be docs-driven, not token-driven. Add or extend docs tooling so the mayor can call something like:

gt_docs({ type: 'wasteland-doctoring' })

The docs should explain how to use DoltHub API endpoints and wasteland SQL semantics, while noting that provider auth is injected automatically by the runtime.

Why Outbound Handlers

This avoids the main risks of direct token exposure:

• No raw provider token in model-visible tool output.
• No token in long-lived prompts or mayor context.
• No token in container env vars.
• No token in command substitution or ps output.
• No token cache files inside the container.
• No env hot-swapping problem for long-running mayor processes.
• OAuth refresh can happen per request in Worker code.

It also gives us a policy/audit point for provider egress.

Implementation Notes

Cloudflare requirements from the outbound handler docs:

• Export ContainerProxy from the Worker entrypoint for outbound interception.
• Set interceptHttps = true on the container class for HTTPS interception.
• Ensure the container trusts /etc/cloudflare/certs/cloudflare-containers-ca.crt at runtime.
• Update the container entrypoint/Docker image to install the ephemeral CA before starting the Bun control server, e.g. copy it into the OS trust store and run update-ca-certificates.
• Consider enableInternet = false or allowedHosts for high-risk/doctoring modes.

Potential code areas:

• services/gastown/src/dos/TownContainer.do.ts or wherever TownContainerDO extends/uses Cloudflare Containers.
• services/gastown/src/gastown.worker.ts exports, to include ContainerProxy if not already exported.
• services/gastown/container/Dockerfile and Dockerfile.dev for CA trust setup.
• services/gastown/container/plugin/* for gt_docs / mayor guidance.
• Credential resolution likely through existing Gastown/Wasteland/Git token service paths.

Wasteland Doctoring Docs

Add gt_docs({ type: 'wasteland-doctoring' }) or equivalent docs access. It should cover:

• DoltHub API base URLs and common endpoints.
• How to read SQL from a ref/branch.
• How to write SQL to a branch.
• Wasteland branch naming: wl/<rig>/<wantedId>.
• Core tables: wanted, completions, stamps, rigs.
• Lifecycle invariants:
  • claimed: wanted.claimed_by is set.
  • in_review: wanted.evidence_url is set and a completions row should exist.
  • completed: accepted completion should have validation/stamp linkage.
• Common repair recipe: missing completion for an in-review wanted item.
• Safety rules:
  • Prefer branch writes, not direct upstream main writes.
  • Read before write.
  • Scope SQL to one wanted item.
  • Avoid schema changes.
  • Avoid broad DELETE/UPDATE statements.

Guardrails

Suggested policy for initial implementation:

• Only enable DoltHub outbound auth for wasteland-connected towns.
• Restrict to known provider hosts.
• Consider enabling broader write access only after the mayor requests doctoring docs or enters a doctoring workflow.
• Log request metadata but never credentials:
  • provider
  • method
  • host/path
  • town id
  • container id
  • agent id if available
  • response status
• Do not log request bodies by default, because SQL may contain sensitive data.
• If the container supplies its own Authorization header, either reject or replace it and redact logs.

Open Questions

• Should DoltHub outbound auth be always-on for wasteland-connected towns, or enabled temporarily by an explicit doctoring workflow?
• Can we reliably map outbound requests to the active agent/mayor, or only to container/town?
• Should we still keep a break-glass gt_get_fresh_token for workflows outbound handlers cannot cover?
• How much local dev support is needed in wrangler dev, given the CA/trust-store requirements?

Acceptance Criteria

• A mayor in a wasteland-connected town can call DoltHub API endpoints from the container without manually handling a DoltHub token.
• Provider OAuth tokens are injected only by trusted Worker/outbound-handler code and are not exposed to the container process.
• Token refresh happens transparently when needed.
• gt_docs({ type: 'wasteland-doctoring' }) provides enough schema/API guidance to repair a missing-completion-style incident.
• Outbound provider requests are auditable without logging secrets.