fix(webhook): --port advertises a local listener but only sets tunnel metadata #106

Summary

webhook start --port says it selects a local HTTP listening port, and the startup output presents the ngrok URL as forwarding to that port. The implementation instead serves the webhook handler directly on the ngrok listener; the supplied port only becomes tunnel metadata. This makes the advertised local endpoint misleading for local CRC testing and port selection.

Runtime or environment

• Latest published xurl release: v1.3.4; the current default branch main and release tag resolve to 18dcb447f090667171ff23666a05d6d387e2aa73.
• Published Darwin arm64 release archive verified against its published checksum; its version and help commands were executed in an isolated home directory.
• Pinned dependency in go.mod: golang.ngrok.com/ngrok v1.13.0.

Steps to reproduce

1. Run xurl webhook start --help. The published binary prints the following description for -p, --port:

Local port for the webhook server to listen on (ngrok will forward to this port) (default 8080)

2. Trace CreateWebhookCommand in cli/webhook.go: the flag sets webhookPort, which forms localhost:<port> and is passed to config.WithForwardsTo inside ngrok.Listen; after successful tunnel creation, the command registers /webhook on a mux and calls http.Serve(ngrokListener, mux).
3. For runtime confirmation, configure OAuth 1.0a credentials with a consumer secret and a valid ngrok authtoken, start xurl webhook start -p 18081, wait for tunnel establishment, and compare a CRC request to http://localhost:18081/webhook?crc_token=test with the public tunnel's /webhook?crc_token=test endpoint. This step was not executed: no live ngrok account or authtoken was used.

Expected behavior

The port help and startup output should accurately describe the endpoint users can contact. If --port is advertised as a local listening port, the webhook endpoint should listen there. If serving directly on the ngrok listener is the intended behavior, the help and forwarding output should describe that behavior accurately.

Actual behavior

The published binary still prints the local-listener promise. Static inspection shows no local bind using the chosen port: its only functional use is setting the ngrok ForwardsTo string, and HTTP is served on the tunnel listener itself. The startup messages nevertheless say that ngrok is forwarding to the local port. Runtime absence of the local socket after a successfully established tunnel has not been measured.

Evidence

• Expected source: the executed release help above; flag registration in cli/webhook.go promises a local listening port.
• Failure source: tunnel creation and forwarding output pass the selected address only to WithForwardsTo; HTTP serving uses ngrokListener directly.
• Evidence provenance: static
• Local verification: static-proof
• Reproduction completeness: incomplete
• Missing fact: a measured localhost connection or socket inspection after successful tunnel establishment with a valid ngrok authtoken.

The primary violation evidence is the reachable command implementation and pinned dependency source; the release help was also directly observed. Runtime reproduction with an established tunnel was not run. The supported entry point is webhook start, registered by CreateRootCommand; a configured OAuth 1.0a consumer secret passes the credential guard, and successful ngrok.Listen reaches the direct HTTP serve call. There is no intervening local bind using webhookPort.

The pinned dependency's WithForwardsTo documentation describes a string displayed through the API or dashboard. Its module source, config/forwards_to.go, assigns cfg.ForwardsTo = string(fwd); it does not create a local TCP listener or forwarder. The dependency's TunnelInfo.ForwardsTo documentation likewise calls this a human-readable dashboard/API string.

Restoration check

With a successfully established tunnel and a chosen port, compare the actual listening endpoint with the CLI's help and startup output. If a local endpoint is advertised, a CRC request to that endpoint must reach the webhook handler; otherwise the CLI must accurately describe direct tunnel serving and avoid claiming that the selected port is listening locally. Verify the public webhook handler still receives CRC requests. The intended design and repair remain the maintainers' choice.

Triage assessment

• Impact level: P2
• Assessment status: provisional
• Impact basis: The CLI advertises a local endpoint that the source does not create, which can misdirect local webhook testing and port-conflict troubleshooting. No live-tunnel failure or affected-user frequency was measured.
• Workaround status: unverified
• Workaround basis: The source exposes the webhook handler through the public ngrok URL, but using that URL as a testing workaround was not verified with a live tunnel.