x402 pre-merge follow-up: seller gateway, unsettled metric, verifyOnly warning (#345)

* feat(x402/buyer): detect 2xx without X-PAYMENT-RESPONSE and expose via metric

Post-#343, settlement moved off the Traefik ForwardAuth hop and became the
seller's responsibility. The buyer sidecar calls ConfirmSpend on any upstream
2xx regardless of whether X-PAYMENT-RESPONSE is present, so a seller that
returns 200 without settling silently consumes the payer's voucher with no
observable signal. This matches the W2/W9 gap flagged in the PR #343 review.

- Add OnPaymentUnsettled callback to replayableX402Transport. Fires exactly
  when the upstream returns 2xx but no successful X-PAYMENT-RESPONSE is
  emitted, logs a WARN, and increments a new counter.
- Add PaymentEventUnsettled event type.
- Add obol_x402_buyer_payment_unsettled_confirmations_total metric with
  upstream/remote_model labels. Operators should alert on any non-zero value.
- Pin invariant with two new tests:
  - TestProxy_UpstreamSuccessNoSettlementHeader_IncrementsUnsettledMetric
  - TestProxy_UpstreamSuccessWithSettlementHeader_DoesNotIncrementUnsettledMetric
- Pin mux symmetry invariant that both /chat/completions and
  /v1/chat/completions route identically — catches the class of regression
  that produced the PR #343 /v1 add/revert/re-add churn.

* fix(x402/forwardauth): warn on verifyOnly=false, shrink facilitator timeout to 5s

Addresses W7 and W8 from the PR #343 review.

W7 — verifyOnly=false footgun: VerifyOnly is the right name for the flag in
the in-process gateway context but is semantically load-bearing for Traefik
ForwardAuth, where the auth hop cannot observe the upstream response. If an
operator flips x402-pricing.yaml verifyOnly=false believing it enables "real"
settlement, the verifier will debit the payer before the upstream serves the
request. We cannot remove the flag without a broader refactor of
internal/inference/gateway.go, so instead:
  - NewForwardAuthMiddleware now logs a loud WARNING at construction when
    VerifyOnly=false, explaining the safe usage.
  - cmd/x402-verifier/main.go emits the same warning on startup and log-scrub
    filters will surface it.
  - ForwardAuthConfig.VerifyOnly documents the invariant ("MUST be true
    behind Traefik ForwardAuth"), so a contributor flipping it gets the
    explanation inline.

W8 — facilitator timeout: reduce http.Client.Timeout from 30s to 5s.
/verify is a cheap signature check; anything beyond 5s is a network problem
the caller should see quickly rather than having every paid request hang
for half a minute on a slow facilitator.

Tests:
- TestForwardAuth_VerifyOnlyFalse_EmitsStartupWarning pins the warning text.
- TestForwardAuth_VerifyOnlyTrue_NoStartupWarning is the negative control so
  operators don't train themselves to filter the warning out.

* chore(embed): lint :latest image tags with pin-by-digest policy

Addresses W4 from the PR #343 review. The /v1 back-and-forth on PR #343
(add → revert → re-add) was consistent with a deployed x402-buyer:latest
image lagging behind main, and the fix hardcoded /v1 in the LiteLLM template
instead of pinning the image. Same risk applies to x402-verifier and
serviceoffer-controller which also ship as :latest.

- New internal/embed/embed_image_pin_test.go scans every embedded template
  and fails when a new :latest appears without an allowlist entry. The
  allowlist currently covers the three obolnetwork images pending digest
  pinning; each entry carries a short reason. Removing an entry without
  replacing :latest in the YAML fails the test (stale-allowlist check).
- Inline TODO(image-pin) comments in llm.yaml and x402.yaml explain the
  policy at the point of violation so contributors who touch the deployment
  spec see it.

This does not pin the images (that requires GHCR access to produce the
digest) — it establishes the contract and makes drift visible.

* feat(x402): route sell http through seller gateway

* fix(obolup): harden installer writes and tty prompts

* docs: keep seller gateway report in pr body only

* feat(model): add master token accessor (#347)

* feat(sell): register by default with explicit opt-out (#349)

* feat(sell): warn that --register is off-chain only

* feat(sell): register by default with explicit opt-out

* feat(sell): show registration summary in sell status

* test(sell): cover registration defaults and sync skill docs

* feat(openclaw): surface generated agent wallet (#348)

* fix(stack): preload openclaw image in dev k3d (#352)

* feat(x402-buyer): expose confirm-spend persistence failures (#351)

---------

Co-authored-by: bussyjd <bussyjd@users.noreply.github.com>

Author: bussyjd

cmd/obol/model.go

@@ -23,6 +23,7 @@ func modelCommand(cfg *config.Config) *cli.Command {
 		Commands: []*cli.Command{
 			modelSetupCommand(cfg),
 			modelStatusCommand(cfg),
+			modelTokenCommand(cfg),
 			modelSyncCommand(cfg),
 			modelPullCommand(),
 			modelListCommand(cfg),
@@ -31,6 +32,28 @@ func modelCommand(cfg *config.Config) *cli.Command {
 	}
 }
 
+func modelTokenCommand(cfg *config.Config) *cli.Command {
+	return &cli.Command{
+		Name:  "token",
+		Usage: "Print the LiteLLM master token for API access",
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			u := getUI(cmd)
+
+			token, err := model.GetMasterKey(cfg)
+			if err != nil {
+				return err
+			}
+
+			if u.IsJSON() {
+				return u.JSON(map[string]string{"token": token})
+			}
+
+			u.Print(token)
+			return nil
+		},
+	}
+}
+
 func modelSetupCommand(cfg *config.Config) *cli.Command {
 	return &cli.Command{
 		Name:  "setup",

cmd/obol/model_test.go

@@ -0,0 +1,38 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/ObolNetwork/obol-stack/internal/config"
+)
+
+func TestModelCommand_Structure(t *testing.T) {
+	cfg := &config.Config{}
+	cmd := modelCommand(cfg)
+
+	if cmd.Name != "model" {
+		t.Fatalf("command name = %q, want model", cmd.Name)
+	}
+
+	expected := map[string]bool{
+		"setup":  false,
+		"status": false,
+		"token":  false,
+		"sync":   false,
+		"pull":   false,
+		"list":   false,
+		"remove": false,
+	}
+
+	for _, sub := range cmd.Commands {
+		if _, ok := expected[sub.Name]; ok {
+			expected[sub.Name] = true
+		}
+	}
+
+	for name, found := range expected {
+		if !found {
+			t.Errorf("missing subcommand %q", name)
+		}
+	}
+}

cmd/obol/openclaw.go

@@ -275,6 +275,36 @@ func openclawWalletCommand(cfg *config.Config) *cli.Command {
 					}, getUI(cmd))
 				},
 			},
+			{
+				Name:      "address",
+				Usage:     "Show the wallet address for an OpenClaw instance",
+				ArgsUsage: "[instance-name]",
+				Action: func(ctx context.Context, cmd *cli.Command) error {
+					args := cmd.Args().Slice()
+
+					if len(args) == 0 {
+						addr, err := openclaw.ResolveWalletAddress(cfg)
+						if err != nil {
+							return err
+						}
+						getUI(cmd).Print(addr)
+						return nil
+					}
+
+					id, _, err := openclaw.ResolveInstance(cfg, args)
+					if err != nil {
+						return err
+					}
+
+					walletsUI := getUI(cmd)
+					walletInfo, err := openclaw.ReadWalletMetadata(openclaw.DeploymentPath(cfg, id))
+					if err != nil {
+						return err
+					}
+					walletsUI.Print(walletInfo.Address)
+					return nil
+				},
+			},
 			{
 				Name:      "list",
 				Usage:     "List wallets for OpenClaw instances",

cmd/obol/openclaw_test.go

@@ -0,0 +1,28 @@
+package main
+
+import "testing"
+
+func TestOpenClawWalletCommand_Structure(t *testing.T) {
+	cfg := newTestConfig(t)
+	cmd := openclawCommand(cfg)
+	wallet := findSubcommand(t, cmd, "wallet")
+
+	expected := map[string]bool{
+		"backup":  false,
+		"restore": false,
+		"address": false,
+		"list":    false,
+	}
+
+	for _, sub := range wallet.Commands {
+		if _, ok := expected[sub.Name]; ok {
+			expected[sub.Name] = true
+		}
+	}
+
+	for name, found := range expected {
+		if !found {
+			t.Errorf("missing wallet subcommand %q", name)
+		}
+	}
+}